AI 编程工具配置笔记

# 需要 Node.js 18+
npm install -g @anthropic-ai/claude-code
claude --version

{
  "model": "sonnet",
  "permissions": {
    "allow": [
      "Bash(git status:*)",
      "Bash(npm run test:*)",
      "Read(**/*.md)"
    ],
    "ask": ["Bash(git push:*)"],
    "deny": [
      "Read(./.env)",
      "Read(**/*.pem)",
      "Bash(curl:*)"
    ]
  },
  "env": {
    "MY_API_ENDPOINT": "https://example.com"
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "jq -r '.tool_input.command' >> ~/.claude/bash-log.txt" }
        ]
      }
    ]
  }
}

# 全局偏好（~/.claude/CLAUDE.md）
- 默认用 pnpm，不要用 npm
- 提交信息遵循 Conventional Commits
- 改完代码必须跑测试，不要跳过

# 项目规则（./CLAUDE.md）
- 本项目是 Next.js 14 App Router，组件放 src/components
- API 路由统一返回 { code, data, message } 结构
- 数据库变更必须先写 migration，禁止直接改表

---
name: deploy
description: 部署当前项目到生产环境。当用户说"上线"、"部署"、"发布"时使用。
---

# 部署流程

1. 运行 pnpm build，失败则停止并报告
2. 打 tag：git tag v$(date +%Y%m%d)-$(git rev-parse --short HEAD)
3. 执行 deploy.sh，把输出贴给用户确认
4. 部署后 curl 健康检查端点，5 分钟内每 30s 一次

# 本地 stdio 服务器
claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem ~/projects

# 远程 HTTP 服务器
claude mcp add --transport http docs https://example.com/mcp \
  --header "Authorization: Bearer XXX"

# 项目级（写入 .mcp.json，可提交 Git）
claude mcp add -s project db -- npx -y @bytebase/dbhub --dsn postgres://...

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
    }
  }
}

# 模型与审批
model = "gpt-5-codex"
# never | on-failure | on-request（untrusted 已移除）
approval_policy = "on-request"
# read-only | workspace-write | danger-full-access
sandbox_mode = "workspace-write"

# MCP 服务器
[mcp_servers.docs]
command = "npx"
args = ["-y", "mcp-deepwiki@latest"]

[mcp_servers.db]
command = "uvx"
args = ["postgres-mcp", "--access-mode=restricted"]

# 自定义模型网关（第三方 / 自建中转）
[model_providers.mygateway]
name = "My Gateway"
base_url = "https://gateway.example.com/v1"
env_key = "MY_GATEWAY_API_KEY"
model_provider = "mygateway"

# 历史与日志
[history]
persistence = "save-all"

# 全局规则 ~/.codex/AGENTS.md
- 你是资深 Go 工程师，优先标准库，谨慎引入第三方依赖
- 任何写操作前先用 git status 确认工作区干净
- 不确定的需求先问，不要猜

# 项目规则 ./AGENTS.md
- 本项目使用 Cobra 组织 CLI，新命令放 cmd/ 下并注册到 root
- 错误处理统一 wrapping：fmt.Errorf("xxx: %w", err)

npm install -g @earendil-works/pi-coding-agent
pi --version

{
  "defaultModel": "deepseek/deepseek-flash",
  "defaultThinkingLevel": "high",
  // 按模型指定思考级别：provider/modelId -> off~max
  "modelThinkingLevels": {
    "deepseek/deepseek-flash": "max"
  },
  // 默认工具 + 追加 codemode
  "defaultTools": ["+codemode"],
  // 自动压缩：剩余 token 低于 16384 时触发
  "compaction": {
    "enabled": true,
    "reserveTokens": 16384,
    "keepRecentTokens": 20000
  }
}

---
name: pdf-tools
description: Extract text and tables from PDF files. Use when reading, converting, or inspecting PDFs.
disable-model-invocation: false
---

# PDF tools

Read `references/formats.md` before converting a document.
Run scripts relative to this skill directory.

---
description: Review staged git changes
argument-hint: "[focus]"
---
Review the staged changes. Focus on ${1:-correctness, security, and error handling}.

# 本地 stdio 服务器（用户级）
pi mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem .
pi mcp list

# 远程 HTTP 服务器
pi mcp add docs --url https://example.com/mcp --bearer-token-env-var DOCS_TOKEN

# 项目级（--local / -l）
pi mcp add -l tools --env API_KEY='${TOOLS_KEY}' -- uvx tools-mcp

{
  "mcpServers": {
    "exa": {
      "type": "http",
      "url": "https://mcp.exa.ai/mcp",
      "headers": { "x-api-key": "sk-****" },
      "directTools": true
    },
    "deepwiki": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-deepwiki@latest"]
    }
  }
}

export ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic
export ANTHROPIC_AUTH_TOKEN=sk-你的 DeepSeek API Key

# 把 Claude 各档位模型映射到 DeepSeek 模型
export ANTHROPIC_MODEL=deepseek-flash[1m]
export ANTHROPIC_DEFAULT_OPUS_MODEL=deepseek-flash[1m]
export ANTHROPIC_DEFAULT_SONNET_MODEL=deepseek-flash[1m]
export ANTHROPIC_DEFAULT_HAIKU_MODEL=deepseek-flash
export CLAUDE_CODE_SUBAGENT_MODEL=deepseek-flash

# 然后正常启动
cd /path/to/project && claude

{
  "providers": {
    "deepseek": {
      "baseUrl": "https://api.deepseek.com/v1",
      "api": "openai-completions",
      "apiKey": "sk-****",
      "compat": {
        "supportsDeveloperRole": false,
        "requiresReasoningContentOnAssistantMessages": true,
        "thinkingFormat": "openai"
      },
      "models": [
        {
          "id": "deepseek-chat",
          "name": "DeepSeek Chat",
          "contextWindow": 1000000,
          "maxTokens": 8000,
          "reasoning": false
        },
        {
          "id": "deepseek-reasoner",
          "name": "DeepSeek Reasoner",
          "contextWindow": 1000000,
          "maxTokens": 32000,
          "reasoning": true,
          "thinkingLevelMap": {
            "minimal": null,
            "low": "medium",
            "medium": "high",
            "high": "high",
            "xhigh": "high",
            "max": "high"
          }
        }
      ]
    }
  }
}

# 1. initialize：握手，协商协议版本与能力
→ { "protocolVersion": "2025-03-26", "capabilities": { "roots": {} }, "clientInfo": {...} }
← { "capabilities": { "tools": {}, "resources": {} }, "serverInfo": {...} }

# 2. tools/list：发现工具（名称 + 描述 + JSON Schema 参数）
→ { "method": "tools/list" }
← { "tools": [{ "name": "query", "description": "...", "inputSchema": {...} }] }

# 3. tools/call：模型决定调用时执行
→ { "method": "tools/call", "params": { "name": "query", "arguments": {...} } }
← { "content": [{ "type": "text", "text": "..." }], "isError": false }

# 4. notifications/initialized 等通知消息双向流动

pdf-tools/
├── SKILL.md          # 必需：frontmatter + 指令正文
├── scripts/          # 可选：可执行脚本，比长指令更可靠
├── references/       # 可选：按需阅读的参考资料（不预载）
└── assets/           # 可选：模板、配置等资源

---
name: pdf-tools
description: Extract text and tables from PDF files. Use when reading, converting, or inspecting PDFs.
---

# PDF tools

Read `references/formats.md` before converting a document.
Run scripts relative to this skill directory.