From ad796655271163e395d45ccd3dcd8af2ee06fa09 Mon Sep 17 00:00:00 2001 From: Yaojia Wang Date: Sat, 14 Mar 2026 20:23:32 +0100 Subject: [PATCH] Sync --- 2 - Projects/PVE Security Scanner.md | 302 +++++++++ .../Everything Claude Code 完整指南.md | 266 ++++++++ .../Everything Claude Code 用法速查.md | 182 ++++++ 4 - Resources/HomeLab Infrastructure.md | 326 ++++++++++ .../OpenBB Invest API - K8s Infrastructure.md | 140 +++++ 4 - Resources/OpenClaw-Skill-Reference.md | 111 ++++ 4 - Resources/OpenVAS Usage Guide.md | 403 ++++++++++++ ...8213000 Everything Claude Code 最佳实践.md | 47 ++ ...0 Everything Claude Code Agent 编排模式.md | 52 ++ ...13200 Everything Claude Code Token 优化.md | 47 ++ ...0 Everything Claude Code 多服务编排详解.md | 586 ++++++++++++++++++ ...8223000 Claude Code Memory 日常最佳实践.md | 192 ++++++ README.md | 70 +++ 13 files changed, 2724 insertions(+) create mode 100644 2 - Projects/PVE Security Scanner.md create mode 100644 4 - Resources/Everything Claude Code 完整指南.md create mode 100644 4 - Resources/Everything Claude Code 用法速查.md create mode 100644 4 - Resources/HomeLab Infrastructure.md create mode 100644 4 - Resources/OpenBB Invest API - K8s Infrastructure.md create mode 100644 4 - Resources/OpenClaw-Skill-Reference.md create mode 100644 4 - Resources/OpenVAS Usage Guide.md create mode 100644 6 - Zettelkasten/20260308213000 Everything Claude Code 最佳实践.md create mode 100644 6 - Zettelkasten/20260308213100 Everything Claude Code Agent 编排模式.md create mode 100644 6 - Zettelkasten/20260308213200 Everything Claude Code Token 优化.md create mode 100644 6 - Zettelkasten/20260308221500 Everything Claude Code 多服务编排详解.md create mode 100644 6 - Zettelkasten/20260308223000 Claude Code Memory 日常最佳实践.md diff --git a/2 - Projects/PVE Security Scanner.md b/2 - Projects/PVE Security Scanner.md new file mode 100644 index 0000000..d15dc71 --- /dev/null +++ b/2 - Projects/PVE Security Scanner.md @@ -0,0 +1,302 @@ +--- +created: "2026-03-08" +type: project +status: active +deadline: "" +tags: + - homelab + - security + - proxmox + - networking +--- + +# PVE Security Scanner + +## Goal + +在 Proxmox VE 上搭建一台专用的内网安全扫描 VM，用于定期进行网络安全评估、漏洞扫描和合规检查。 + +## Architecture + +``` ++------------------+ +| PVE Host | +| +--------------+| PVE Firewall (Layer 1) +| | Scanner VM || - IN: only admin IPs -> SSH/9392 +| | Ubuntu 24.04 || - OUT: internal nets + update_targets IPSET +| | 4C / 8G / 80G|| +| +--------------+| +| | | ++--------|--------+ + | vmbr0 (bridge) + | + ======|==================== Internal Network (192.168.68.0/24) + | | | | + [Host] [Host] [Host] [Switch/Router] +``` + +## VM Specs + +| Resource | Value | +|----------|-------| +| Hostname | network-scanner | +| IP | 192.168.68.84 | +| OS | Ubuntu 24.04 (cloud-init) | +| Kernel | 6.8.0-101-generic | +| CPU | 4 cores (host type) | +| RAM | 8 GB | +| Disk | 80 GB | +| Network | vmbr0 bridge, 192.168.68.0/24 | +| SSH User | kai (1Password managed key) | +| Admin User | scanner-admin | + +## Security Architecture (Defense in Depth) + +### Layer 1: PVE Firewall (Hypervisor) + +在 Proxmox 层面限制 VM 网络访问，即使 VM 被攻陷也无法绕过。 + +| Direction | Rule | Purpose | +|-----------|------|---------| +| IN | Admin IPs -> TCP 22 | SSH 管理 | +| IN | Admin IPs -> TCP 443, 9392 | OpenVAS Web UI | +| IN | Internal nets -> ICMP | Ping | +| OUT | -> Internal nets (all) | 扫描内网 | +| OUT | -> update_targets IPSET TCP 80/443 | 漏洞库更新、包管理 | +| OUT | -> UDP 53/123 | DNS / NTP | +| Default | DROP | 其他全部拒绝 | + +Config: `/etc/pve/firewall/200.fw` + +Admin IPs 默认 `192.168.68.0/24`（整个内网段），可通过 `SCANNER_ADMIN_IPS` 环境变量覆盖。 + +### Layer 2: nftables (VM Internal) + +VM 内部使用 nftables 做第二层防护，包含动态封禁功能。 + +**Key features:** +- `blocked_ips` set: 动态 IP 封禁（带超时自动解封） +- `ssh_bruteforce` set: SSH 暴力破解自动检测（3次/分钟触发，15分钟封禁） +- Output policy DROP: 出站默认拒绝，仅白名单放行 +- 所有 DROP 事件记录日志 +- Docker 接口使用 `iifname "docker*"` / `iifname "br-*"` 通配（不要求接口预先存在） + +**管理命令:** + +```bash +# 查看规则 +nft list ruleset + +# 手动封禁 IP（1小时） +nft add element inet firewall blocked_ips { 1.2.3.4 timeout 1h } + +# 查看被封禁的 IP +nft list set inet firewall blocked_ips + +# 重载规则 +systemctl restart nftables +``` + +Config: `/etc/nftables.conf` + +### Layer 3: SSH Hardening + +| Setting | Value | +|---------|-------| +| Authentication | Public key only (1Password) | +| Root login | Disabled | +| Max auth tries | 10 | +| Ciphers | chacha20-poly1305, aes256-gcm | +| KEX | sntrup761x25519, curve25519 | +| Fail2ban | 3 failures -> 1h ban (nftables backend) | +| AllowUsers | `scanner-admin kai` | +| Forwarding | DisableForwarding yes | +| Banner | /etc/issue.net | + +Config: `/etc/ssh/sshd_config.d/99-scanner-hardening.conf` + +### Layer 4: System Hardening + +**Kernel (sysctl):** +- IP forwarding disabled +- ICMP redirects ignored +- SYN flood protection (syncookies) +- Reverse path filtering (anti-spoofing) +- Martian packet logging +- ASLR enabled, ptrace restricted + +**Auditing:** +- `auditd`: 监控 /etc, auth, sudo, network, cron, scanner config 变更 +- `AIDE`: 文件完整性检查 (daily 3am) +- `Lynis`: 安全审计 (weekly Sunday 2am) +- Core dumps disabled + +Config: `/etc/sysctl.d/99-security-scanner.conf`, `/etc/audit/rules.d/scanner-audit.rules` + +## Installed Tools + +| Tool | Purpose | Usage | +|------|---------|-------| +| **OpenVAS/Greenbone** | 全面漏洞管理平台 | Web UI `https://192.168.68.84` (nginx -> gsad) | +| **Nmap** | 网络发现、端口扫描 | `nmap -sV --script=safe ` | +| **Nuclei** | 快速漏洞扫描 (模板驱动, SHA256 校验) | `nuclei -u ` | +| **httpx** | HTTP 探测、服务识别 (SHA256 校验) | `httpx -l hosts.txt` | +| **Nikto** | Web 服务器扫描 | `nikto -h ` | +| **testssl.sh** | TLS/SSL 安全检测 | `testssl ` | +| **NetExec** | SMB/RDP/WinRM 评估 | `netexec smb ` | + +## Scanning Workflow + +### Quick Scan (Automated) + +```bash +/opt/scans/scripts/quick-scan.sh 192.168.68.0/24 +``` + +Steps: +1. Host discovery (`nmap -sn`) +2. Port scan top 1000 (`nmap -sV --script=safe`) +3. HTTP service detection (`httpx`) +4. Vulnerability scan (`nuclei` medium/high/critical) + +Results saved to `/opt/scans/results//` + +### Full Scan (OpenVAS) + +1. Start containers: `cd /opt/greenbone && docker compose up -d` +2. Wait for feed sync (first time: 30-60 min) +3. Access Web UI: `https://192.168.68.84` (self-signed cert, accept warning) +4. Create Target -> Create Task -> Run Scan +5. Export report (PDF/CSV) + +### Targeted Scans + +```bash +# TLS/SSL audit +testssl 192.168.68.10:443 + +# Web server scan +nikto -h https://192.168.68.10 + +# SMB assessment +netexec smb 192.168.68.0/24 + +# Full port scan single host +nmap -sV --script=safe -p- -T4 192.168.68.10 +``` + +## Monitoring + +| Check | Schedule | Tool | +|-------|----------|------| +| Disk usage | Every 6h | `/opt/scans/scripts/check-disk.sh` | +| OpenVAS health | Every 30min | `/opt/scans/scripts/check-openvas.sh` | +| File integrity | Daily 3am | AIDE | +| Security audit | Weekly Sun 2am | Lynis | +| Old results cleanup | Weekly Sun 4am | find (maxdepth 1, >90 days, logged) | +| Nuclei templates | Weekly Mon 5am | `nuclei -update-templates` | +| Daily summary | Daily | Logwatch | + +Logs: `/var/log/scanner/` + +## Deployment + +### Method: Cloud-Init Template Clone + +1. PVE Web UI -> 选中 Cloud-Init 模板 -> 右键 Clone (Full Clone) +2. Cloud-Init 标签设置: user `kai`, SSH key (1Password), IP `192.168.68.84/24` +3. Hardware: 4C / 8G / 80G disk + +### Copy Scripts to VM + +```bash +scp -r C:/Users/yaoji/git/pve-security-scanner/vm kai@192.168.68.84:/tmp/scanner-setup +``` + +### Execute (in order) + +```bash +# 设置环境变量 +export SCANNER_ADMIN_IPS='192.168.68.0/24' +export SCANNER_DNS_SERVERS='192.168.68.1' + +# 一键执行（或逐个执行） +sudo -E bash /tmp/scanner-setup/setup.sh + +# 或逐个: +sudo -E bash /tmp/scanner-setup/01-system-harden.sh +sudo -E bash /tmp/scanner-setup/02-firewall.sh +sudo -E bash /tmp/scanner-setup/04-install-tools.sh # Docker 先装 +sudo usermod -aG docker scanner-admin # 补加 docker 组 +sudo -E bash /tmp/scanner-setup/03-ssh-harden.sh # 再跑 SSH +sudo -E bash /tmp/scanner-setup/05-monitoring.sh +sudo -E bash /tmp/scanner-setup/06-docker-autostart.sh + +# OpenVAS 密码 +cd /opt/greenbone && docker compose up -d +docker compose exec -u gvmd gvmd gvmd --user=admin --new-password= + +# 重启 +sudo shutdown -r now +``` + +### Post-Deployment Checklist + +- [x] VM created from cloud-init template +- [x] SSH key configured (1Password, ed25519) +- [x] System hardening (01) applied +- [x] nftables firewall (02) applied - ADMIN_IPS = 192.168.68.0/24 +- [x] Docker installed (Ubuntu source fix applied) +- [x] SSH hardening (03) applied - AllowUsers scanner-admin kai, MaxAuthTries 10 +- [x] Security tools (04) installed +- [x] Monitoring (05) configured +- [x] Docker autostart (06) enabled - systemd greenbone-openvas.service +- [x] OpenVAS Web UI accessible - `https://192.168.68.84` (nginx port 443+9392) +- [ ] Feed sync complete (in progress, ~30-60 min) +- [ ] First quick scan completed +- [ ] `lynis audit system` score verified + +## Deployment Notes + +### Issues Encountered + +1. **Docker source wrong distro**: 脚本原写 Debian 源，实际系统是 Ubuntu 24.04 (noble)。已修复为自动检测 `${ID}` (debian/ubuntu) +2. **nftables rate limit 不能用 define**: `define SSH_RATE_LIMIT = 5/minute` 语法错误，nftables 不支持 define 变量做 rate limit，改为内联值 +3. **`iif "docker0"` 要求接口已存在**: Docker 未安装时 docker0 不存在导致报错，改为 `iifname "docker*"` 通配 +4. **03-ssh-harden.sh docker 组不存在**: 需先运行 04 安装 Docker，再运行 03 创建用户 +5. **SSH `sshd.service` not found**: Ubuntu 用 `ssh.service`，已修复为 `ssh 2>/dev/null || sshd` +6. **AllowUsers 只有 scanner-admin**: cloud-init 用户 `kai` 被拒绝登录，已加入 AllowUsers +7. **MaxAuthTries 3 太小**: 1Password 管理多个 key 逐个尝试会超限，改为 10 +8. **ADMIN_IPS 设成 VM 自身 IP**: 导致工作站无法 SSH，改为整网段 `192.168.68.0/24` +9. **Greenbone 镜像名变更**: `greenbone/xxx` 已迁移到 `registry.community.greenbone.net/community/xxx`，架构改为 nginx + gsad + gsa 分离 +10. **nginx 9392 端口重定向到 443**: 需同时暴露 443 端口，docker-compose 已加 `0.0.0.0:443:443` + +### Recommended Execution Order (revised) + +01 -> 02 -> 04 (Docker) -> 03 (SSH, needs docker group) -> 05 -> 06 + +## Scripts Location + +Repo: https://git.colacoder.com/kai/pve-security-scanner + +``` +pve-security-scanner/ +├── pve/ +│ ├── create-vm.sh # VM creation (idempotent) +│ └── firewall.sh # PVE-level firewall (env var guard) +├── vm/ +│ ├── setup.sh # One-click ordered execution +│ ├── 01-system-harden.sh # OS hardening +│ ├── 02-firewall.sh # nftables rules +│ ├── 03-ssh-harden.sh # SSH + fail2ban +│ ├── 04-install-tools.sh # Security tools (auto-detect distro) +│ ├── 05-monitoring.sh # Logging + cron +│ └── 06-docker-autostart.sh # OpenVAS systemd service +└── README.md +``` + +## Related + +- [[Proxmox VE]] +- [[Home Network]] +- [[Security Best Practices]] diff --git a/4 - Resources/Everything Claude Code 完整指南.md b/4 - Resources/Everything Claude Code 完整指南.md new file mode 100644 index 0000000..19200da --- /dev/null +++ b/4 - Resources/Everything Claude Code 完整指南.md @@ -0,0 +1,266 @@ +--- +created: "2026-03-08 21:30" +type: resource +tags: [claude-code, AI-tools, development-workflow, reference] +source: "https://github.com/affaan-m/everything-claude-code" +--- + +# Everything Claude Code 完整指南 + +生产级 Claude Code 插件系统，包含 65+ skills、16 agents、40+ commands、hooks 和 rules。v1.8.0，经过 10+ 个月的高强度日常使用演化。 + +## 项目架构 + +``` +everything-claude-code/ +├── agents/ (16个) - 专用子代理 +├── skills/ (65个) - 工作流定义和领域知识 +├── commands/ (40个) - slash 命令 +├── hooks/ - 基于事件的自动化 +├── rules/ - 始终遵循的规则（按语言分层） +├── scripts/ - 跨平台 Node.js 工具脚本 +├── mcp-configs/- MCP 服务器配置模板 +└── contexts/ - 动态注入的上下文文件 +``` + +## 安装 + +```bash +# 插件安装 +/plugin marketplace add affaan-m/everything-claude-code +/plugin install everything-claude-code@everything-claude-code + +# Rules 手动安装（插件无法分发规则） +git clone https://github.com/affaan-m/everything-claude-code.git +cd everything-claude-code +./install.sh python typescript # 按需选语言 +``` + +--- + +## 全部 65 Skills + +### 核心基础设施 (9) + +| Skill | 用途 | +|-------|------| +| `agent-harness-construction` | 设计 AI agent 动作空间、工具定义和观测格式 | +| `agentic-engineering` | eval-first 执行、任务分解、成本感知路由 | +| `ai-first-engineering` | AI 优先工程运营模式 | +| `continuous-agent-loop` | 持续自主 agent 循环，含质量门控和恢复 | +| `enterprise-agent-ops` | 长期运行 agent 运维：可观测性、安全边界 | +| `strategic-compact` | 逻辑断点手动压缩上下文 | +| `eval-harness` | 评估驱动开发(EDD)，pass@k 和 pass^k | +| `verification-loop` | 综合验证：构建、lint、测试、安全扫描 | +| `configure-ecc` | 交互式安装向导 | + +### 开发工作流 (7) + +| Skill | 用途 | +|-------|------| +| `autonomous-loops` | 顺序管道到 RFC 驱动多 agent DAG | +| `continuous-learning` | 从 session 自动提取可复用模式 | +| `continuous-learning-v2` | instinct 学习系统，带置信度评分 | +| `ralphinho-rfc-pipeline` | RFC 驱动多 agent DAG 执行 | +| `nanoclaw-repl` | 零依赖 session 感知 REPL | +| `tdd-workflow` | Red-Green-Refactor，80%+ 覆盖率 | +| `search-first` | 先搜索现有工具/库再编码 | + +### 前端 (4) + +| Skill | 用途 | +|-------|------| +| `frontend-patterns` | React/Next.js 模式、状态管理 | +| `frontend-slides` | 动画 HTML 演示文稿 | +| `swiftui-patterns` | SwiftUI 架构、@Observable | +| `liquid-glass-design` | iOS 26 Liquid Glass 设计系统 | + +### 后端 & API (5) + +| Skill | 用途 | +|-------|------| +| `backend-patterns` | Node.js/Express/Next.js 服务端架构 | +| `api-design` | REST API 设计模式 | +| `cost-aware-llm-pipeline` | LLM API 成本优化和模型路由 | +| `content-hash-cache-pattern` | SHA-256 内容哈希缓存 | +| `iterative-retrieval` | 渐进式上下文检索 | + +### 数据库 (3) + +| Skill | 用途 | +|-------|------| +| `postgres-patterns` | PostgreSQL 查询优化、索引、Schema | +| `clickhouse-io` | ClickHouse 分析数据库 | +| `database-migrations` | Schema 变更、零停机部署 | + +### Python + Django (6) + +| Skill | 用途 | +|-------|------| +| `python-patterns` | PEP 8、类型提示、Pythonic 惯用法 | +| `python-testing` | pytest、TDD、fixtures、mock | +| `django-patterns` | Django/DRF 架构、ORM | +| `django-tdd` | pytest-django、factory_boy | +| `django-security` | 认证、CSRF、SQL 注入防护 | +| `django-verification` | Django 验证循环 | + +### Java/Spring Boot (6) + +| Skill | 用途 | +|-------|------| +| `java-coding-standards` | 命名、不可变性、Optional、Stream | +| `jpa-patterns` | 实体设计、关联、查询优化 | +| `springboot-patterns` | Spring Boot 架构、REST API | +| `springboot-tdd` | JUnit 5、Mockito、Testcontainers | +| `springboot-security` | Spring Security 加固 | +| `springboot-verification` | 构建、静态分析、覆盖率 | + +### Go (2) + +| Skill | 用途 | +|-------|------| +| `golang-patterns` | 惯用 Go 模式、并发 | +| `golang-testing` | 表驱动测试、benchmark、fuzz | + +### C++ (2) + +| Skill | 用途 | +|-------|------| +| `cpp-coding-standards` | C++ Core Guidelines | +| `cpp-testing` | GoogleTest + CMake/CTest | + +### Swift (3) + +| Skill | 用途 | +|-------|------| +| `swift-concurrency-6-2` | Swift 6.2 单线程默认 + @concurrent | +| `swift-actor-persistence` | Actor 线程安全持久化 | +| `swift-protocol-di-testing` | 协议注入测试模式 | + +### 测试 & 质量 (3) + +| Skill | 用途 | +|-------|------| +| `e2e-testing` | Playwright E2E、Page Object Model | +| `plankton-code-quality` | 写时质量门控 | +| `skill-stocktake` | Skill 质量审计 | + +### 部署 (3) + +| Skill | 用途 | +|-------|------| +| `deployment-patterns` | CI/CD、回滚、生产就绪检查 | +| `docker-patterns` | Docker Compose、容器安全 | +| `foundation-models-on-device` | Apple FoundationModels 端侧 LLM | + +### 安全 & 代码规范 (5) + +| Skill | 用途 | +|-------|------| +| `security-review` | 认证、输入、secrets 安全检查表 | +| `security-scan` | AgentShield 102 条规则扫描 | +| `coding-standards` | TypeScript/JS/React/Node.js 规范 | +| `regex-vs-llm-structured-text` | 正则 vs LLM 解析选择框架 | +| `project-guidelines-example` | 项目 skill 模板 | + +### 内容 & 商业 (5) + +| Skill | 用途 | +|-------|------| +| `article-writing` | 长文写作 | +| `content-engine` | 多平台内容系统 | +| `market-research` | 竞争分析、行业情报 | +| `investor-materials` | 融资材料 | +| `investor-outreach` | 投资者沟通邮件 | + +### 特殊用途 (2) + +| Skill | 用途 | +|-------|------| +| `visa-doc-translate` | 签证文档双语翻译 PDF | +| `nutrient-document-processing` | Nutrient DWS API 文档处理 | + +--- + +## 16 Agents + +| Agent | 职责 | +|-------|------| +| `planner` | 功能实现规划 | +| `architect` | 系统设计决策 | +| `tdd-guide` | 测试驱动开发 | +| `code-reviewer` | 代码质量审查 | +| `security-reviewer` | 安全漏洞分析 | +| `build-error-resolver` | 编译/运行时错误修复 | +| `e2e-runner` | Playwright E2E 测试 | +| `refactor-cleaner` | 死代码清理 | +| `doc-updater` | 文档更新 | +| `go-reviewer` | Go 代码审查 | +| `go-build-resolver` | Go 构建错误修复 | +| `python-reviewer` | Python 代码审查 | +| `database-reviewer` | PostgreSQL 审查 | +| `chief-of-staff` | 多渠道通信管理 | +| `harness-optimizer` | Agent 框架优化 | +| `loop-operator` | 循环任务运维 | + +--- + +## 常用 Commands + +### 开发核心 +`/plan` `/tdd` `/e2e` `/code-review` `/build-fix` `/verify` `/test-coverage` `/refactor-clean` + +### 多 Agent 编排 +`/multi-plan` `/multi-execute` `/multi-frontend` `/multi-backend` `/orchestrate` + +### 学习演化 +`/learn` `/learn-eval` `/evolve` `/instinct-status` `/instinct-export` `/instinct-import` + +### v1.8.0 新增 +`/loop-start` `/loop-status` `/model-route` `/quality-gate` `/harness-audit` `/promote` + +--- + +## Hooks 系统 + +### PreToolUse +- tmux 自动启动和提醒 +- git push 前 review 提醒 +- 文档文件警告 +- 逻辑断点压缩建议 +- 持续学习观察（异步） + +### PostToolUse +- PR 创建日志 +- 质量门控检查 +- 自动格式化 (Prettier/Biome) +- TypeScript 类型检查 +- console.log 警告 + +### Stop +- console.log 最终检查 +- Session 状态持久化 +- 模式提取评估 +- Token 成本追踪 + +### 控制 +```bash +ECC_HOOK_PROFILE=standard # minimal/standard/strict +ECC_DISABLED_HOOKS="pre:bash:tmux-reminder,post:edit:typecheck" +``` + +--- + +## Related + +- [[Everything Claude Code 用法速查]] +- [[Claude Code Memory 日常最佳实践]] +- [[Everything Claude Code 最佳实践]] +- [[Everything Claude Code Agent 编排模式]] +- [[Everything Claude Code Token 优化]] + +## Source + +- [GitHub Repo](https://github.com/affaan-m/everything-claude-code) +- [Shortform Guide](https://github.com/affaan-m/everything-claude-code/blob/main/the-shortform-guide.md) +- [Longform Guide](https://github.com/affaan-m/everything-claude-code/blob/main/the-longform-guide.md) diff --git a/4 - Resources/Everything Claude Code 用法速查.md b/4 - Resources/Everything Claude Code 用法速查.md new file mode 100644 index 0000000..ce9662d --- /dev/null +++ b/4 - Resources/Everything Claude Code 用法速查.md @@ -0,0 +1,182 @@ +--- +created: "2026-03-08 22:10" +type: resource +tags: [claude-code, AI-tools, development-workflow, cheatsheet] +source: "https://github.com/affaan-m/everything-claude-code" +--- + +# Everything Claude Code 用法速查 + +按使用场景分类的快速参考手册。组件完整列表见 [[Everything Claude Code 完整指南]]。 + +--- + +## 一、按开发阶段分类 + +### 1. 规划阶段 + +| 场景 | 用什么 | 怎么用 | +|------|--------|--------| +| 复杂功能设计 | `/plan` 命令 → planner agent | 输入需求，生成分阶段实施计划，等用户确认后再动手 | +| 系统架构决策 | architect agent | 自动启用，做 trade-off 分析、模式推荐、可扩展性评审 | +| 多模型并行规划 | `/multi-plan` | Claude + Codex + Gemini 并行出方案，对比择优 | +| 研究优先 | search-first skill | 先搜 GitHub/npm/PyPI 找现有实现，再决定是否自己写 | + +### 2. 编码阶段 + +| 场景 | 用什么 | 怎么用 | +|------|--------|--------| +| 新功能开发 | `/tdd` 命令 → tdd-guide agent | 强制 RED→GREEN→REFACTOR 流程，先写测试再实现，验证 80%+ 覆盖率 | +| 修 Bug | tdd-guide agent（自动启用） | 先写复现测试，再修复，确保不回归 | +| 构建失败 | `/build-fix` → build-error-resolver agent | 最小改动修复编译/类型错误，不动架构 | +| Go 构建报错 | `/go-build` | 专门处理 go build、go vet、linter 问题 | + +### 3. 质量保障阶段 + +| 场景 | 用什么 | 怎么用 | +|------|--------|--------| +| 代码审查 | `/code-review` → code-reviewer agent | 写完代码后必须用，检查安全性、质量、可维护性 | +| 安全审查 | security-reviewer agent（自动启用） | 涉及用户输入/认证/API/敏感数据时自动触发，检测 OWASP Top 10 | +| E2E 测试 | `/e2e` → e2e-runner agent | 生成 Playwright 测试，截图/录屏/trace，自动隔离 flaky 测试 | +| 死代码清理 | `/refactor-clean` → refactor-cleaner agent | 用 knip/depcheck 扫描未使用代码并安全删除 | +| 快速质量门禁 | `/quality-gate` | 提交前快速检查，轻量级 | + +### 4. 语言专用审查 + +| 语言 | 命令 | 检查内容 | +|------|------|----------| +| Python | `/python-review` | PEP 8、类型提示、安全、ruff/mypy/pylint | +| Go | `/go-review` | 惯用 Go 模式、并发安全、error handling、staticcheck | +| Go 测试 | `/go-test` | 表驱动测试、覆盖率分析 | +| TypeScript | 自动 hook | 保存后自动 Prettier 格式化 + TypeScript 类型检查 | +| SQL/数据库 | database-reviewer agent | 查询优化、RLS 安全、连接池、Supabase 最佳实践 | + +--- + +## 二、按自动化机制分类（Hooks） + +| 时机 | Hook | 效果 | +|------|------|------| +| 执行 Bash 前 | auto-tmux-dev | 自动在 tmux 中启动 dev server | +| 执行 Bash 前 | tmux-reminder | 长时间命令提醒用 tmux | +| 执行 Bash 前 | git-push-reminder | git push 前提醒 review | +| 写文件前 | doc-file-warning | 阻止创建非标准文档文件 | +| 编辑后 | prettier-format | 自动格式化 JS/TS 文件 | +| 编辑后 | typecheck | .ts/.tsx 文件编辑后自动类型检查 | +| 编辑后 | console-log-warning | 警告残留的 console.log | +| 编辑后 | quality-gate | 编辑后快速质量检查 | +| 会话开始 | session-start | 加载上次上下文、检测包管理器 | +| 会话结束 | session-end | 持久化会话状态 | +| 会话结束 | evaluate-session | 提取可复用模式（持续学习） | + +控制方式： +- `ECC_HOOK_PROFILE=minimal|standard|strict` — 按级别启用 +- `ECC_DISABLED_HOOKS=hook1,hook2` — 禁用特定 hook + +--- + +## 三、按高级场景分类 + +### 1. 多模型协作 + +| 命令 | 用途 | +| ----------------- | ----------------------------------- | +| `/multi-plan` | Claude + Codex + Gemini 并行规划 | +| `/multi-execute` | 跨多个模型后端并行执行 | +| `/multi-frontend` | 多前端框架并行开发（React/Vue/Svelte/Angular） | +| `/multi-backend` | 多后端栈并行开发（Node/Python/Go/Java） | +| `/multi-workflow` | 复杂多服务编排 | + +### 2. 自主循环 + +| 命令 | 用途 | +|------|------| +| `/loop-start` | 启动自主循环：sequential / continuous-pr / rfc-dag / infinite | +| `/loop-status` | 监控循环进度、检测卡住 | +| `/harness-audit` | 评估 harness 配置：工具覆盖、上下文效率、质量门禁、成本 | + +### 3. 持续学习 + +| 命令 | 用途 | +|------|------| +| `/learn` | 从当前会话提取可复用模式，保存为 skill | +| `/learn-eval` | 从 eval 会话中提取模式 | +| `/skill-create` | 分析 git 历史自动生成 SKILL.md | +| `/instinct-status` | 查看所有已学习的 instinct 及置信度 | +| `/instinct-export` | 导出 instinct 给队友共享 | +| `/instinct-import` | 导入其他项目的 instinct | + +### 4. 模型路由 + +| 模型 | 适合场景 | +|------|----------| +| Haiku 4.5 | 轻量 agent、pair programming、高频调用（省 3x 成本） | +| Sonnet 4.6 | 主力开发、编排多 agent、复杂编码 | +| Opus 4.6 | 架构决策、深度推理、研究分析 | + +用 `/model-route` 自动路由到合适模型。 + +--- + +## 四、安装方式 + +```bash +# 安装通用 + 语言规则到 ~/.claude/rules/ +./install.sh typescript python golang swift + +# 安装到 Cursor +./install.sh --target cursor typescript + +# 安装到 Antigravity +./install.sh --target antigravity golang +``` + +--- + +## 五、MCP 外部集成（建议不超过 10 个） + +| 服务 | 用途 | 需要 Key | +|------|------|----------| +| github | PR/Issue/Repo 操作 | GITHUB_PERSONAL_ACCESS_TOKEN | +| supabase | 数据库操作 | project-ref | +| vercel | 部署管理 | - | +| firecrawl | 网页抓取 | FIRECRAWL_API_KEY | +| exa-web-search | 研究搜索 | EXA_API_KEY | +| clickhouse | 分析查询 | - | +| context7 | 实时文档查询 | - | +| sequential-thinking | 链式推理 | - | + +--- + +## 六、一句话速查表 + +| 我想... | 用 | +|---------|-----| +| 规划一个大功能 | `/plan` | +| 写功能并保证测试覆盖 | `/tdd` | +| 审查刚写的代码 | `/code-review` | +| 修编译错误 | `/build-fix` | +| 跑端到端测试 | `/e2e` | +| 清理死代码 | `/refactor-clean` | +| 更新文档 | `/update-docs` | +| 审查 Python 代码 | `/python-review` | +| 审查 Go 代码 | `/go-review` | +| 多模型并行出方案 | `/multi-plan` | +| 启动自主循环 | `/loop-start` | +| 评估 harness 质量 | `/harness-audit` | +| 从会话中学习模式 | `/learn` | + +--- + +## Related + +- [[Everything Claude Code 完整指南]] +- [[Everything Claude Code 多服务编排详解]] +- [[Claude Code Memory 日常最佳实践]] +- [[Everything Claude Code 最佳实践]] +- [[Everything Claude Code Agent 编排模式]] +- [[Everything Claude Code Token 优化]] + +## Source + +- [GitHub Repo](https://github.com/affaan-m/everything-claude-code) diff --git a/4 - Resources/HomeLab Infrastructure.md b/4 - Resources/HomeLab Infrastructure.md new file mode 100644 index 0000000..03d37f4 --- /dev/null +++ b/4 - Resources/HomeLab Infrastructure.md @@ -0,0 +1,326 @@ +--- +created: "2026-03-10" +type: resource +tags: [infrastructure, homelab, kubernetes, ci-cd, gitops] +source: "HomeLab 部署实践" +--- + +# HomeLab 基础设施文档 + +## 网络拓扑概览 + +``` +[NAS (192.168.68.x)] ── Gitea (Docker), AdGuard Home (DNS) + | +[192.168.68.x 内网] + | +[K8s Cluster] + ├── k8s-cp1 (Control Plane) ── 192.168.68.11 + ├── k8s-w1 (Worker) ── 192.168.68.21 + └── k8s-w2 (Worker) ── 192.168.68.22 + ├── Docker Registry ── NodePort 30500 + ├── Drone CI ── NodePort 30344 (webhook), Ingress drone.k8s.home + ├── ArgoCD ── Ingress argocd.k8s.home + ├── ingress-nginx ── LoadBalancer 192.168.68.240 + └── 应用 (invest-api 等) +``` + +## DNS (AdGuard Home) + +DNS 服务器: `192.168.68.63` + +### DNS 重写规则 + +| 域名 | IP | 说明 | +|------|-----|------| +| `invest-api.k8s.home` | 192.168.68.240 | OpenBB 投资分析 API | +| `drone.k8s.home` | 192.168.68.240 | Drone CI | +| `argocd.k8s.home` | 192.168.68.240 | ArgoCD | + +注意: 所有 `*.k8s.home` 域名都应指向 ingress-nginx 的 LoadBalancer IP `192.168.68.240`（由 MetalLB 分配），而不是节点 IP。 + +## 已部署应用 + +| 应用 | URL | 命名空间 | 说明 | +|------|-----|----------|------| +| OpenBB Invest API | `https://invest-api.k8s.home` | invest-api | 投资分析 REST API（50 端点）| +| Drone CI | `https://drone.k8s.home` | drone | CI/CD | +| ArgoCD | `https://argocd.k8s.home` | argocd | GitOps 部署 | +| Swagger UI | `https://invest-api.k8s.home/docs` | invest-api | API 文档 | + +## Kubernetes 集群 + +### 节点信息 + +| 节点 | 角色 | IP | 说明 | +|------|------|----|------| +| k8s-cp1 | Control Plane | 192.168.68.11 | API Server, etcd, scheduler | +| k8s-w1 | Worker | 192.168.68.21 | 应用负载 | +| k8s-w2 | Worker | 192.168.68.22 | 应用负载 | + +### 集群组件 + +| 组件 | 版本/说明 | +|------|----------| +| Kubernetes | v1.35.0 | +| 容器运行时 | containerd 1.7.28 | +| CNI | 默认 | +| 负载均衡 | MetalLB (分配 IP: 192.168.68.240) | +| Ingress | ingress-nginx (External IP: 192.168.68.240) | +| 存储 | Proxmox CSI | +| 证书管理 | cert-manager | + +### kubeconfig + +- API Server: `https://192.168.68.11:6443` +- 认证方式: 证书认证 (admin 用户) +- 本地配置: `C:\Users\yaoji\.kube\config` +- 获取方式: 从 Control Plane `/etc/kubernetes/admin.conf` 拷贝 + +### 已部署命名空间 + +| 命名空间 | 用途 | +|----------|------| +| argocd | ArgoCD GitOps | +| drone | Drone CI/CD | +| registry | Docker Registry | +| ingress-nginx | Ingress 控制器 | +| cert-manager | TLS 证书管理 | +| metallb-system | 负载均衡 | +| csi-proxmox / proxmox-csi | 存储 | +| invest-api | OpenBB 投资分析 API | + +--- + +## Git 服务 (Gitea) + +| 项目 | 值 | +|------|-----| +| 部署位置 | NAS Docker | +| URL | `https://git.colacoder.com` | +| SSH | `ssh://git@git.colacoder.com:2200/` | +| 管理员用户 | kai | +| 邮箱 | wangyaojia@gmail.com | + +### Gitea 配置注意事项 + +`app.ini` 中需要的配置: + +```ini +[webhook] +ALLOWED_HOST_LIST = private +SKIP_TLS_VERIFY = true +``` + +- `ALLOWED_HOST_LIST = private` — 允许 webhook 发送到内网地址 +- `SKIP_TLS_VERIFY = true` — 允许连接自签名证书的服务 +- 修改后需要重启 Gitea 容器 + +### 仓库列表 + +| 仓库 | 用途 | +|------|------| +| kai/openbb-invest-api | OpenBB 投资分析 API | + +--- + +## CI/CD (Drone CI) + +### 部署信息 + +| 项目 | 值 | +|------|-----| +| 命名空间 | drone | +| 版本 | 2.12.1 | +| Ingress | `https://drone.k8s.home` | +| Runner 类型 | Kubernetes Runner | +| Runner 容量 | 4 并发 | + +### 访问方式 + +| 方式 | 地址 | +|------|------| +| Web UI | `https://drone.k8s.home` | +| Webhook (给 Gitea 用) | `http://192.168.68.21:30344/hook` | +| API | `http://192.168.68.21:30344/api/` | +| API Token | `c7hDypuu5p41r5k6svR0x6QomInqrE6f` | + +### Drone Server 配置 (ConfigMap: drone) + +| 键 | 值 | +|-----|-------| +| DRONE_GITEA_SERVER | `https://git.colacoder.com/` | +| DRONE_GITEA_CLIENT_ID | `c95249a5-9cad-4813-89b4-3f4f9f7d3cee` | +| DRONE_SERVER_HOST | drone.k8s.home | +| DRONE_SERVER_PROTO | https | +| DRONE_USER_CREATE | username:kai,admin:true | + +### Drone Runner 配置 (ConfigMap: drone-runner-drone-runner-kube) + +| 键 | 值 | +|-----|-------| +| DRONE_RPC_HOST | drone.drone.svc.cluster.local:8080 | +| DRONE_RPC_PROTO | http | +| DRONE_NAMESPACE_DEFAULT | drone | +| DRONE_RUNNER_CAPACITY | 4 | + +### RBAC + +Runner ServiceAccount (`drone:drone-runner-drone-runner-kube`) 需要在 `drone` namespace 有以下权限: +- secrets: create, delete +- pods, pods/log: get, create, delete, list, watch, update + +Helm 安装时 RBAC 错误地创建在 `default` namespace，需要手动在 `drone` namespace 创建 Role 和 RoleBinding。 + +### Gitea Webhook 配置 + +| 项目 | 值 | +|------|-----| +| Target URL | `http://192.168.68.21:30344/hook` | +| Content Type | application/json | +| Secret | `KE0HQksXhJ53ojiLwgAIp0JC4QCl1NsE` | +| Events | Push | + +注意: Drone 无法自动在 Gitea 创建 webhook（OAuth 权限问题），需要手动创建。 + +### Pipeline 模板 (.drone.yml) + +使用 kaniko 构建（Kubernetes Runner 不支持 privileged 模式的 `plugins/docker`）: + +```yaml +kind: pipeline +type: kubernetes +name: build-and-push + +trigger: + branch: [main, develop] + event: [push, custom] + +steps: + - name: build-and-push + image: gcr.io/kaniko-project/executor:debug + commands: + - > + /kaniko/executor + --context=/drone/src + --dockerfile=Dockerfile + --destination=192.168.68.11:30500/IMAGE_NAME:${DRONE_COMMIT_SHA:0:8} + --destination=192.168.68.11:30500/IMAGE_NAME:latest + --insecure + --skip-tls-verify +``` + +--- + +## Docker Registry + +| 项目 | 值 | +|------|-----| +| 命名空间 | registry | +| 镜像 | registry:2 | +| Service | NodePort 30500 | +| 存储 | PVC 10Gi | +| 访问地址 | `http://192.168.68.11:30500` | +| 基础设施仓库 | `C:\Users\yaoji\git\ColaCoder\k8s-infra\registry\` | + +### Registry API + +```bash +# 查看所有镜像 +curl http://192.168.68.11:30500/v2/_catalog + +# 查看镜像 tags +curl http://192.168.68.11:30500/v2/IMAGE_NAME/tags/list +``` + +### Worker 节点 containerd 配置 + +两个 Worker 节点 `/etc/containerd/config.toml` 中添加: + +```toml +[plugins."io.containerd.grpc.v1.cri".registry.mirrors."192.168.68.11:30500"] + endpoint = ["http://192.168.68.11:30500"] +[plugins."io.containerd.grpc.v1.cri".registry.mirrors."registry.registry.svc.cluster.local:5000"] + endpoint = ["http://registry.registry.svc.cluster.local:5000"] +``` + +修改后需要 `sudo systemctl restart containerd`。Control Plane 不需要配置。 + +### 本地 Docker Desktop 配置 + +`C:\Users\yaoji\.docker\daemon.json`: + +```json +{ + "insecure-registries": ["192.168.68.11:30500"] +} +``` + +修改后需要重启 Docker Desktop。 + +--- + +## ArgoCD + +| 项目 | 值 | +|------|-----| +| 命名空间 | argocd | +| 同步策略 | 自动 (prune + selfHeal) | +| CreateNamespace | true | + +### 已注册应用 + +| 应用 | 源仓库 | 路径 | 分支 | 目标命名空间 | +|------|--------|------|------|-------------| +| invest-api | `https://git.colacoder.com/kai/openbb-invest-api.git` | k8s/base | main | invest-api | + +--- + +## 完整部署流程 (GitOps) + +``` +开发者 git push + ↓ +Gitea 接收代码 + ↓ (webhook) +Drone CI 触发构建 + ↓ (kaniko) +Docker 镜像推送到 Registry (192.168.68.11:30500) + ↓ +ArgoCD 检测 k8s manifest 变化 + ↓ (自动同步) +K8s 拉取镜像并部署 +``` + +--- + +## 踩坑记录 + +### Gitea Webhook + +1. **webhook 被拒**: Gitea 默认不允许发送 webhook 到内网地址，需要 `ALLOWED_HOST_LIST = private` +2. **TLS 验证失败**: 内网自签名证书需要 `SKIP_TLS_VERIFY = true` +3. **403 Forbidden**: Drone OAuth2 应用丢失需要重新创建；webhook 手动创建时需要填写正确的 secret + +### Drone CI + +1. **Runner 无法连接 Server**: Service 端口 8080 但 Runner 连的默认 80，需要在 `DRONE_RPC_HOST` 加 `:8080` +2. **手动触发无反应**: `.drone.yml` trigger event 需要包含 `custom` +3. **RBAC 权限不足**: Helm 把 Role 创建在 `default` namespace，需要手动在 `drone` namespace 创建 +4. **不能用 plugins/docker**: Kubernetes Runner 不支持 privileged 模式，改用 kaniko + +### Docker 镜像 + +1. **OpenBB 需要 home 目录**: `nobody` 用户没有 home，需要创建 `appuser` 并预建 `.openbb_platform` 目录 +2. **OpenBB 需要写入 site-packages**: 启动时写 `.build.lock`，需要 `chown -R appuser:appuser /usr/local/lib/python3.12/site-packages/openbb` + +### DNS / Ingress + +1. **Ingress IP 不是节点 IP**: `*.k8s.home` 域名必须指向 MetalLB 分配的 LoadBalancer IP (`192.168.68.240`)，不是节点 IP (`192.168.68.22`) + +--- + +## Related + +- [[OpenBB Invest API - K8s Infrastructure]] +- [[OpenBB Invest API]] diff --git a/4 - Resources/OpenBB Invest API - K8s Infrastructure.md b/4 - Resources/OpenBB Invest API - K8s Infrastructure.md new file mode 100644 index 0000000..303596c --- /dev/null +++ b/4 - Resources/OpenBB Invest API - K8s Infrastructure.md @@ -0,0 +1,140 @@ +--- +created: "2026-03-09" +type: resource +tags: [kubernetes, infrastructure, devops, drone-ci, argocd, docker-registry] +source: "openbb-invest-api 项目部署实践" +--- + +# OpenBB Invest API - K8s 基础设施 + +## 概述 + +OpenBB Invest API 的完整 Kubernetes 部署架构，包含集群信息、CI/CD 流水线和 GitOps 配置。 + +## 集群 + +| 节点 | 角色 | IP | +|------|------|----| +| k8s-cp1 | control-plane | 192.168.68.11 | +| k8s-w1 | worker | 192.168.68.21 | +| k8s-w2 | worker | 192.168.68.22 | + +- Kubernetes v1.35.0 +- 容器运行时: containerd 1.7.28 +- 负载均衡: MetalLB +- Ingress: ingress-nginx +- 存储: Proxmox CSI +- 证书管理: cert-manager + +## kubeconfig + +- 位置: `C:\Users\yaoji\.kube\config` +- 认证: 证书认证 (admin 用户) +- API server: `https://192.168.68.11:6443` + +## Docker Registry + +- 命名空间: `registry` +- 镜像: `registry:2` +- 服务: NodePort 30500 +- 持久卷: 10Gi +- 访问地址: `http://192.168.68.11:30500` +- 基础设施仓库: `C:\Users\yaoji\git\ColaCoder\k8s-infra\registry\` + +### Worker 节点 containerd 配置 + +两个 worker 节点的 `/etc/containerd/config.toml`: + +```toml +[plugins."io.containerd.grpc.v1.cri".registry.mirrors."192.168.68.11:30500"] + endpoint = ["http://192.168.68.11:30500"] +[plugins."io.containerd.grpc.v1.cri".registry.mirrors."registry.registry.svc.cluster.local:5000"] + endpoint = ["http://registry.registry.svc.cluster.local:5000"] +``` + +Control plane 不需要配置（有 taint，pod 不会调度到上面）。 + +## Drone CI + +- 命名空间: `drone` +- Server: 容器端口 80，Service 端口 8080 +- Runner: Kubernetes runner（容量 4） +- Ingress: `drone.k8s.home` + +### Runner ConfigMap + +| 键 | 值 | +|-----|-------| +| DRONE_RPC_HOST | drone.drone.svc.cluster.local:8080 | +| DRONE_RPC_PROTO | http | +| DRONE_NAMESPACE_DEFAULT | drone | + +### 流水线 (.drone.yml) + +使用 kaniko 构建（k8s runner 不支持 privileged 模式）: + +```yaml +kind: pipeline +type: kubernetes +name: build-and-push +trigger: + branch: [main, develop] + event: [push, custom] +steps: + - name: build-and-push + image: gcr.io/kaniko-project/executor:debug + commands: + - /kaniko/executor + --context=/drone/src + --dockerfile=Dockerfile + --destination=192.168.68.11:30500/invest-api:${DRONE_COMMIT_SHA:0:8} + --destination=192.168.68.11:30500/invest-api:latest + --insecure --skip-tls-verify +``` + +## ArgoCD + +- 命名空间: `argocd` +- Application: `invest-api` +- 源仓库: `https://git.colacoder.com/kai/openbb-invest-api.git`，路径 `k8s/base` +- 目标分支: `main`，命名空间 `invest-api` +- 同步策略: 自动（prune + selfHeal + CreateNamespace） + +## Gitea + +- URL: `https://git.colacoder.com` +- 仓库: `kai/openbb-invest-api` +- SSH: `ssh://git@git.colacoder.com:2200/kai/openbb-invest-api.git` + +## 部署流程 + +1. `git push` 到 Gitea（main/develop 分支） +2. Gitea webhook 触发 Drone CI +3. Drone/kaniko 构建 Docker 镜像并推送到 `192.168.68.11:30500` +4. ArgoCD 检测 `k8s/base/` 中的 manifest 变化并自动同步 +5. k8s 从 registry 拉取镜像并部署 + +## invest-api K8s Manifests (k8s/base/) + +- 命名空间: `invest-api` +- Deployment: 镜像 `192.168.68.11:30500/invest-api:latest`，100m-500m CPU，256Mi-512Mi 内存，健康检查 `/health:8000` +- Service: ClusterIP 端口 8000 +- Secret: `invest-api-secrets`（可选，用于 API 密钥） + +## 本地 Docker Desktop + +`C:\Users\yaoji\.docker\daemon.json`: + +```json +{"insecure-registries": ["192.168.68.11:30500"]} +``` + +## 踩坑记录 + +- **Drone Runner RPC 连接超时**: Runner 默认连接端口 80，但 Service 暴露的是 8080。通过 patch configmap 添加 `:8080` 修复。 +- **Drone 手动触发无反应**: UI 手动触发发送的 event 是 `custom`，需要在 `.drone.yml` trigger 中添加 `custom` event。 +- **kubeconfig 传输损坏**: 通过聊天传输 RSA 私钥会被截断/损坏，需要通过 SSH 直接传输文件。 + +## Related + +- [[OpenBB Invest API]] diff --git a/4 - Resources/OpenClaw-Skill-Reference.md b/4 - Resources/OpenClaw-Skill-Reference.md new file mode 100644 index 0000000..feacb05 --- /dev/null +++ b/4 - Resources/OpenClaw-Skill-Reference.md @@ -0,0 +1,111 @@ +--- +created: "2026-03-10" +type: resource +tags: [openclaw, ai-gateway, claude-code, skill] +source: "https://docs.openclaw.ai/" +--- + +# OpenClaw Skill 参考 + +## 概述 + +OpenClaw 是一个自托管的 AI 网关，将聊天应用（WhatsApp、Telegram、Discord、Slack、Signal、iMessage 等 20+ 渠道）连接到 AI 编码代理。基于 Node.js 22+，使用 WebSocket 控制平面。 + +- 配置文件: `~/.openclaw/openclaw.json`（JSON5 格式，热重载） +- 默认端口: `18789` +- 本地仓库: `C:\Users\yaoji\git\OpenSource\openclaw` +- 文档: https://docs.openclaw.ai/ +- Claude Code Skill 位置: `~/.claude/skills/openclaw/SKILL.md` + +## Skill 覆盖内容 + +### 核心操作 + +| 模块 | 功能 | 关键命令 | +|------|------|----------| +| Gateway | 启动/停止/重启/状态/服务安装 | `openclaw gateway run/start/stop/restart/status` | +| 配置 | JSON5 配置读写/验证/向导 | `openclaw config get/set/unset/validate` | +| Agent | 多 agent 隔离/路由绑定/身份 | `openclaw agents add/bind/unbind/list` | +| Session | 会话列表/清理/作用域管理 | `openclaw sessions/cleanup` | + +### 通讯渠道 + +| 模块 | 功能 | 关键命令 | +|------|------|----------| +| Channel | 添加/登录/状态/能力探测 | `openclaw channels add/login/status/capabilities` | +| Message | 发送/回复/投票/反应/广播/线程 | `openclaw message send/poll/react/broadcast` | + +### 扩展能力 + +| 模块 | 功能 | 关键命令 | +|------|------|----------| +| Skills | 列出/检查 agent 技能 | `openclaw skills list/info/check` | +| Plugins | 安装/启用/更新/卸载 | `openclaw plugins install/enable/update` | +| Hooks（内部） | 事件驱动自动化 | `openclaw hooks list/enable/disable` | +| Webhooks（外部） | HTTP 触发 agent | `POST /hooks/wake`, `POST /hooks/agent` | +| Cron | 定时任务 | `openclaw cron add/edit` | + +### API 与集成 + +- **OpenAI 兼容 API**: `POST /v1/chat/completions`（需开启） +- **RPC 调用**: `openclaw gateway call ` +- **25+ 模型提供商**: Anthropic、OpenAI、Ollama、OpenRouter、Bedrock 等 + +## 关键配置结构 + +``` +openclaw.json +├── identity # 名称/主题/表情 +├── agents # agent 列表/默认值/workspace/model/skills +├── channels # 各渠道配置（whatsapp/telegram/discord/slack...） +├── session # 作用域/重置/维护 +├── skills # 技能条目/加载/安装 +├── plugins # 插件条目/允许/拒绝 +├── tools # web/browser/canvas/media +├── gateway # 端口/绑定/认证/HTTP端点 +├── hooks # webhook + 内部钩子 +├── cron # 定时任务 +├── acp # Agent Control Protocol +├── logging # 日志级别/脱敏 +└── env # 环境变量 +``` + +## Bootstrap 文件 + +放在 agent workspace 根目录: + +- `AGENTS.md` - 操作指令 + 记忆 +- `SOUL.md` - 人格/边界/语气 +- `TOOLS.md` - 用户工具说明 +- `BOOTSTRAP.md` - 一次性引导（运行后删除） +- `IDENTITY.md` - agent 名称/风格 +- `USER.md` - 用户画像 + +## SKILL.md 格式（创建自定义技能） + +```markdown +--- +name: my-skill +description: 技能描述 +requires: + bins: [node] + env: [API_KEY] +install: + - kind: node + package: my-package +--- +# 技能说明和工具定义 +``` + +## 常见工作流 + +1. **初始化**: `npm install -g openclaw@latest && openclaw onboard --install-daemon` +2. **添加渠道**: `openclaw channels add --channel telegram --token TOKEN` +3. **多 agent**: `openclaw agents add work --workspace ~/.openclaw/workspace-work` +4. **API 触发**: `curl -X POST http://127.0.0.1:18789/hooks/agent -H 'Authorization: Bearer TOKEN' -d '{"message":"..."}'` +5. **诊断**: `openclaw doctor --fix && openclaw status --deep` + +## Related + +- [[Claude Code 配置]] +- [[AI 工具链]] diff --git a/4 - Resources/OpenVAS Usage Guide.md b/4 - Resources/OpenVAS Usage Guide.md new file mode 100644 index 0000000..a786863 --- /dev/null +++ b/4 - Resources/OpenVAS Usage Guide.md @@ -0,0 +1,403 @@ +--- +created: "2026-03-08" +type: resource +tags: + - security + - openvas + - vulnerability-scanning + - homelab +--- + +# OpenVAS Usage Guide + +Greenbone OpenVAS 漏洞扫描平台使用指南。基于 Greenbone Community Edition，部署在 [[PVE Security Scanner]] 上。 + +## Access + +| Item | Value | +|------|-------| +| URL | `https://192.168.68.84` | +| Backup URL | `https://192.168.68.84:9392` | +| Username | `admin` | +| Certificate | Self-signed (浏览器需接受警告) | + +## Core Concepts + +| Concept | Description | +|---------|-------------| +| **Target** | 扫描目标，可以是单个 IP、IP 范围、子网 (CIDR) | +| **Port List** | 要扫描的端口集合 (默认提供 All TCP, Top 100, Top 1000 等) | +| **Scan Config** | 扫描策略，控制检测深度和范围 | +| **Task** | 将 Target + Scan Config 组合成一个可执行的扫描任务 | +| **Report** | 扫描结果报告，包含发现的漏洞和风险评级 | +| **Schedule** | 定时执行扫描任务 | +| **Alert** | 扫描完成后的通知动作 (邮件、HTTP 回调等) | +| **NVT** | Network Vulnerability Test，单个漏洞检测脚本 | +| **CVE** | 公共漏洞编号，OpenVAS 关联 CVE 数据库 | +| **CVSS** | 漏洞评分标准 (0-10)，用于风险评级 | + +## Scan Configs (扫描策略) + +| Config | Speed | Depth | Use Case | +|--------|-------|-------|----------| +| **Discovery** | Fast | Low | 仅发现主机和服务，不做漏洞检测 | +| **Host Discovery** | Very Fast | Minimal | 只检测主机是否存活 | +| **System Discovery** | Fast | Low | 发现操作系统和服务版本 | +| **Base** | Medium | Medium | 基础漏洞扫描，不含危险测试 | +| **Full and fast** | Medium | High | 完整扫描，跳过慢速 NVT (推荐日常使用) | +| **Full and deep** | Slow | Very High | 深度扫描，包含所有 NVT | +| **Full and deep ultimate** | Very Slow | Maximum | 包含可能导致服务中断的测试 (慎用) | + +## Quick Start: First Scan + +### Step 1: Create Target + +1. Menu: **Configuration** -> **Targets** +2. Click **New Target** (左上角星号图标) +3. Fill in: + - **Name**: `Internal Network` (或具体名称) + - **Hosts**: `192.168.68.0/24` (或单个 IP) + - **Port List**: 选择 `All TCP and Nmap top 100 UDP` +4. Click **Save** + +### Step 2: Create Task + +1. Menu: **Scans** -> **Tasks** +2. Click **New Task** (左上角星号图标) +3. Fill in: + - **Name**: `Internal Network Scan` + - **Scan Targets**: 选择刚创建的 Target + - **Scanner**: `OpenVAS Default` + - **Scan Config**: 选择策略 (建议首次用 `Full and fast`) +4. Click **Save** + +### Step 3: Run Scan + +1. 在 Task 列表中找到刚创建的任务 +2. 点击绿色 **Start** 按钮 (播放图标) +3. Status 会从 `New` -> `Requested` -> `Running` -> `Done` +4. 扫描时间取决于目标数量和策略： + - 单台主机 Full and fast: 10-30 分钟 + - /24 子网 Full and fast: 2-8 小时 + +### Step 4: View Report + +1. Task 完成后，点击 **Last Report** 日期链接 +2. 报告页面展示所有发现的漏洞 +3. 按 Severity 排序查看高危漏洞 + +## Report Reading + +### Severity Levels + +| Level | CVSS | Color | Action | +|-------|------|-------|--------| +| **Critical** | 9.0-10.0 | Purple | 立即修复 | +| **High** | 7.0-8.9 | Red | 尽快修复 | +| **Medium** | 4.0-6.9 | Orange | 计划修复 | +| **Low** | 0.1-3.9 | Blue | 评估后决定 | +| **Log** | N/A | Grey | 信息收集，无需操作 | + +### Report Sections + +- **Results**: 所有发现的漏洞列表 +- **Hosts**: 按主机分组的结果 +- **Operating Systems**: 检测到的操作系统 +- **Applications**: 检测到的应用程序 +- **TLS Certificates**: SSL/TLS 证书信息 +- **Error Messages**: 扫描过程中的错误 + +### Export Report + +1. 打开 Report +2. 左上角下拉选择格式: + - **PDF** - 适合分享和存档 + - **CSV** - 适合数据分析 + - **XML** - 适合导入其他工具 + - **TXT** - 纯文本摘要 +3. Click download icon + +## Common Scan Scenarios + +### Scenario 1: Scan Single Server + +**Target**: `192.168.68.31` (PostgreSQL server) +**Config**: `Full and fast` +**Port List**: `All TCP and Nmap top 100 UDP` + +重点关注: +- PostgreSQL 版本漏洞 +- SSH 配置问题 +- 系统补丁缺失 + +### Scenario 2: Scan Entire Network + +**Target**: `192.168.68.0/24` +**Config**: `Full and fast` +**Port List**: `All TCP and Nmap top 100 UDP` + +首次扫描建议在非工作时间进行，扫描会产生较大网络流量。 + +### Scenario 3: Web Application Scan + +**Target**: Web 服务器 IP +**Config**: `Full and deep` +**Port List**: `All TCP` + +重点关注: +- HTTP 相关漏洞 (XSS, SQL injection, CSRF) +- TLS 配置 (弱加密、过期证书) +- Web 服务器版本泄露 + +### Scenario 4: Compliance Check + +**Target**: 所有关键服务器 +**Config**: `Full and fast` + +对照报告检查: +- 是否有默认密码 +- 是否有未打补丁的服务 +- 是否有不安全的协议 (telnet, FTP, SSLv3) + +## Scheduled Scans + +### Create Schedule + +1. Menu: **Configuration** -> **Schedules** +2. Click **New Schedule** +3. Fill in: + - **Name**: `Weekly Internal Scan` + - **First Run**: 选择开始时间 (建议非工作时间，如周日凌晨 2:00) + - **Period**: `1 week` + - **Duration**: 留空 (无时间限制) +4. Click **Save** + +### Assign Schedule to Task + +1. Edit existing Task +2. **Schedule** 字段选择刚创建的 Schedule +3. Save + +Task 会按计划自动执行，报告自动生成。 + +## Alerts (通知) + +### Email Alert + +1. Menu: **Configuration** -> **Alerts** +2. Click **New Alert** +3. Fill in: + - **Name**: `High Severity Email` + - **Event**: `Task run status changed` -> `Done` + - **Condition**: `Severity at least` -> `7.0` (High) + - **Method**: `Email` + - **To Address**: 你的邮箱 + - **From Address**: `scanner@localhost` +4. Click **Save** +5. 在 Task 中关联此 Alert + +Note: 需要配置 VM 的 SMTP 发送邮件。 + +## Credential Scans (认证扫描) + +认证扫描可以检测更多漏洞（如本地提权、软件版本），因为扫描器可以登录目标系统。 + +### Create SSH Credential + +1. Menu: **Configuration** -> **Credentials** +2. Click **New Credential** +3. Fill in: + - **Name**: `Linux SSH Scan` + - **Type**: `Username + SSH Key` 或 `Username + Password` + - **Username**: 目标系统的用户名 + - **Password/Key**: 对应的认证信息 + - **Auto Generate**: No +4. Click **Save** + +### Use in Target + +1. Edit Target +2. **SSH Credential** 字段选择创建的 Credential +3. Save + +认证扫描会发现更多漏洞（如未打补丁的本地包、内核漏洞）。 + +## Performance Tips + +| Tip | Effect | +|-----|--------| +| 缩小端口范围 | 减少扫描时间 | +| 用 `Full and fast` 而非 `Full and deep` | 快 2-5x，覆盖 90% 漏洞 | +| 分段扫描大网络 | 避免超时和资源耗尽 | +| 避免工作时间扫描 | 减少对生产环境影响 | +| 定期更新 Feed | 保持漏洞库最新 | + +## Maintenance + +### Update Vulnerability Feed + +Feed 自动通过 Docker 容器更新。手动触发： + +```bash +ssh kai@192.168.68.84 +cd /opt/greenbone +sudo docker compose pull +sudo docker compose up -d +``` + +### Check Feed Status + +Web UI: **Administration** -> **Feed Status** + +| Feed | Description | +|------|-------------| +| NVT | 漏洞检测脚本 (最重要) | +| SCAP | CVE/CPE 数据 | +| CERT | 安全公告 | +| GVMD_DATA | 扫描策略和端口列表 | + +所有 Feed 应显示 `Current`。如果显示 `Update in progress`，等待同步完成。 + +### Backup + +```bash +# 备份所有 Docker volumes +ssh kai@192.168.68.84 +cd /opt/greenbone +sudo docker compose down +sudo tar czf /tmp/greenbone-backup-$(date +%Y%m%d).tar.gz \ + /var/lib/docker/volumes/greenbone-community-edition_* +sudo docker compose up -d +``` + +### Reset Admin Password + +```bash +ssh kai@192.168.68.84 +cd /opt/greenbone +sudo docker compose exec -u gvmd gvmd gvmd --user=admin --new-password= +``` + +## Report Workflow (报告使用流程) + +### Priority Matrix + +| Priority | CVSS | Example | Timeline | Action | +|----------|------|---------|----------|--------| +| **Critical** | 9.0-10.0 | 远程代码执行、默认密码、未授权访问 | 24h 内 | 立即修复 | +| **High** | 7.0-8.9 | 本地提权、敏感信息泄露、SQL 注入 | 1 周内 | 尽快修复 | +| **Medium** | 4.0-6.9 | 弱加密、软件版本过旧、TLS 配置不当 | 1 月内 | 排期修复 | +| **Low** | 0.1-3.9 | 信息收集、Banner 暴露、非敏感信息泄露 | 按需 | 评估后决定 | + +### Step-by-Step Workflow + +**Step 1: Export Report** +- 打开 Report -> 左上角选择格式 +- 导出 **PDF** (存档分享) + **CSV** (数据分析) +- 建议按日期归档: `scans/2026-03-09-full-network.pdf` + +**Step 2: Triage by Host** +- 点 **Hosts** 标签，按漏洞数量排序 +- 识别问题最多的主机，优先处理 + +**Step 3: Analyze Vulnerabilities** +- 点进具体漏洞，关注以下字段： + - **Summary**: 漏洞描述（是什么） + - **Impact**: 被利用后的影响（为什么要修） + - **Solution**: 修复建议（怎么修）-- 最有价值的部分 + - **CVE Reference**: 关联的 CVE 编号（可查详细信息） + - **Affected Software/OS**: 受影响的软件版本 + +**Step 4: Create Remediation Plan** +- 按优先级为每个 Critical/High 漏洞创建修复任务 +- 记录：主机 IP、漏洞名称、CVE、修复方案、负责人 +- Medium 漏洞汇总为批量修复任务（如统一升级某软件） + +**Step 5: Fix and Rescan** +- 修复完成后，对同一 Target 重新扫描 +- 对比两次 Report，确认漏洞已消除 +- Web UI: **Scans** -> **Reports** 可以看历史趋势 + +### Recurring Scan Process + +建议建立周期性扫描流程： + +``` +周日凌晨 2:00 自动全网扫描 (OpenVAS Schedule) + | +周一上午 查看报告，按优先级分类 + | +周一-周五 修复 Critical 和 High 漏洞 + | +下周日 自动复扫，对比改善情况 + | +每月最后一周 导出月度报告，归档存储 +``` + +Setup: **Configuration** -> **Schedules** -> 创建 Weekly Schedule (Sunday 02:00) + +### Report Comparison (趋势分析) + +跟踪安全改善情况： + +| Metric | How to Track | +|--------|-------------| +| Critical/High 漏洞数量变化 | 每周报告对比 | +| 平均修复时间 | 记录发现日期和修复日期 | +| 新增 vs 已修复 | 对比相邻两次扫描 | +| 最高风险主机 | 按 Host 的 Severity Score 排序 | + +### Common Findings and Fixes + +| Finding | Typical Fix | +|---------|------------| +| SSH weak algorithms | 更新 `/etc/ssh/sshd_config` 加密套件 | +| SSL/TLS outdated | 升级到 TLS 1.2+，禁用弱密码套件 | +| Default credentials | 修改默认密码，禁用默认账户 | +| Missing patches | `apt upgrade` / 系统补丁更新 | +| Open unnecessary ports | 关闭不需要的服务，配置防火墙 | +| HTTP without HTTPS | 配置 TLS 证书，强制 HTTPS 重定向 | +| SMBv1 enabled | 禁用 SMBv1，启用 SMBv2/v3 | +| SNMP public community | 修改 community string 或禁用 SNMP | + +## CLI Access (gvm-tools) + +除了 Web UI，也可以通过命令行操作： + +```bash +ssh kai@192.168.68.84 +cd /opt/greenbone + +# 进入 gvm-tools 容器 +sudo docker compose exec gvm-tools bash + +# 列出所有 task +gvm-cli --gmp-username admin --gmp-password \ + socket --socketpath /run/gvmd/gvmd.sock \ + --xml '' + +# 列出所有 target +gvm-cli --gmp-username admin --gmp-password \ + socket --socketpath /run/gvmd/gvmd.sock \ + --xml '' +``` + +## Troubleshooting + +| Problem | Solution | +|---------|----------| +| Web UI 打不开 | `sudo docker compose ps` 检查容器状态 | +| 登录失败 | Reset admin password (见上方) | +| Feed 一直 updating | 首次同步需 30-60 分钟，耐心等待 | +| 扫描卡在 Requested | 检查 ospd-openvas 容器日志: `sudo docker compose logs ospd-openvas` | +| 扫描结果为空 | 确认 Feed 已同步完成；检查目标网络是否可达 | +| 只扫到本机 | ospd-openvas 需要 `network_mode: host` 才能到达局域网 | +| Feed is syncing | 漏洞库同步中，等几分钟到半小时，Feed Status 全部 Current 后再扫 | +| 扫描速度很慢 | 减少目标范围；使用 `Full and fast` 策略 | +| 容器反复重启 | `sudo docker compose logs ` 查看错误 | +| 磁盘空间不足 | `df -h` 检查；清理旧报告和 Docker 无用镜像 `sudo docker system prune` | + +## Related + +- [[PVE Security Scanner]] - 部署文档和安全架构 +- [[Security Best Practices]] diff --git a/6 - Zettelkasten/20260308213000 Everything Claude Code 最佳实践.md b/6 - Zettelkasten/20260308213000 Everything Claude Code 最佳实践.md new file mode 100644 index 0000000..42993c1 --- /dev/null +++ b/6 - Zettelkasten/20260308213000 Everything Claude Code 最佳实践.md @@ -0,0 +1,47 @@ +--- +created: "2026-03-08 21:30" +type: zettel +tags: [claude-code, best-practices, AI-tools] +source: "https://github.com/affaan-m/everything-claude-code" +--- + +# Everything Claude Code 最佳实践 + +## 上下文窗口是最稀缺资源 + +200k 上下文窗口在启用太多 MCP 后可能只剩 70k。三条铁律： + +1. **MCP < 10 个启用，< 80 个工具活跃** — 用 CLI + skill 替代 MCP（如 `gh` CLI 替代 GitHub MCP） +2. **关闭 auto compact** — 在逻辑断点手动 `/compact`，避免在关键推理中被截断 +3. **CLAUDE.md < 200 行** — 详细规则放 `rules/`，利用 skill 的渐进式加载 + +## Token 成本路由 + +90% 任务用 Sonnet，只在架构决策和安全分析时用 Opus，搜索探索用 Haiku。设置： + +```json +{ "model": "sonnet", "env": { "MAX_THINKING_TOKENS": "10000", "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "50" } } +``` + +用 mgrep 替代 grep 可减少约 50% token 使用。 + +## 记忆持久化 + +- 每个 session 结束保存摘要到 `.tmp` 文件（记录：有效方法、无效尝试、待办事项） +- 下次 session 提供文件路径作为上下文 +- 动态注入：`claude --system-prompt "$(cat ~/.claude/contexts/dev.md)"` + +## 并行但有纪律 + +- 最小可行并行度 — 不盲目开多终端 +- Git worktree 隔离并行实例 +- `/rename` 命名每个 chat，`/fork` 分叉非重叠工作 +- 级联方法：新任务右开，从左到右扫描，同时不超过 3-4 个 + +--- + +## Related + +- [[Everything Claude Code 完整指南]] +- [[Everything Claude Code Agent 编排模式]] +- [[Everything Claude Code Token 优化]] diff --git a/6 - Zettelkasten/20260308213100 Everything Claude Code Agent 编排模式.md b/6 - Zettelkasten/20260308213100 Everything Claude Code Agent 编排模式.md new file mode 100644 index 0000000..b4b5df3 --- /dev/null +++ b/6 - Zettelkasten/20260308213100 Everything Claude Code Agent 编排模式.md @@ -0,0 +1,52 @@ +--- +created: "2026-03-08 21:31" +type: zettel +tags: [claude-code, agent-orchestration, workflow] +source: "https://github.com/affaan-m/everything-claude-code" +--- + +# Everything Claude Code Agent 编排模式 + +## 顺序阶段模式 + +``` +Phase 1: RESEARCH (Explore agent) → research-summary.md +Phase 2: PLAN (planner agent) → plan.md +Phase 3: IMPLEMENT (tdd-guide) → code changes +Phase 4: REVIEW (code-reviewer) → review-comments.md +Phase 5: VERIFY (build-error-resolver) → done or loop +``` + +规则：每个 agent 一个输入一个输出；输出成为下一阶段输入；不跳过阶段；阶段间 `/clear`；中间结果保存到文件。 + +## 迭代检索模式 + +解决子代理上下文丢失问题： + +1. 主代理评估每个子代理返回 +2. 在接受前追问（传递目标上下文，不只是查询） +3. 子代理回源获取答案 +4. 循环直到充分（最多 3 轮） + +核心洞察：子代理只知道字面查询，不知道请求背后的目的。必须传递 objective context。 + +## 两终端启动模式（新项目） + +- **终端 1 (Scaffolding Agent)**: 创建项目结构、配置 CLAUDE.md、rules、agents +- **终端 2 (Research Agent)**: 连接服务、搜索文档、创建 PRD、架构图 + +## 模型选择 + +| 任务 | 模型 | 原因 | +|------|------|------| +| 搜索/探索/文档 | Haiku | 快速便宜 | +| 多文件实现/PR 审查 | Sonnet | 编码最佳平衡 | +| 架构决策/安全分析/复杂 debug | Opus | 深度推理 | + +--- + +## Related + +- [[Everything Claude Code 多服务编排详解]] +- [[Everything Claude Code 最佳实践]] +- [[Everything Claude Code 完整指南]] diff --git a/6 - Zettelkasten/20260308213200 Everything Claude Code Token 优化.md b/6 - Zettelkasten/20260308213200 Everything Claude Code Token 优化.md new file mode 100644 index 0000000..48074d0 --- /dev/null +++ b/6 - Zettelkasten/20260308213200 Everything Claude Code Token 优化.md @@ -0,0 +1,47 @@ +--- +created: "2026-03-08 21:32" +type: zettel +tags: [claude-code, token-optimization, cost] +source: "https://github.com/affaan-m/everything-claude-code" +--- + +# Everything Claude Code Token 优化 + +## 节省 60%+ 成本的四个策略 + +### 1. 模型路由 +90% 任务用 Sonnet，Haiku 做搜索/文档，Opus 只用于架构和安全。用 `/model-route` 自动路由。 + +### 2. MCP 精简 +- 保持 < 10 个 MCP 启用 +- 用 CLI + skill 替代 MCP wrapper（如 gh CLI 替代 GitHub MCP） +- 每个 MCP 消耗上下文窗口，多到一定程度 200k 变 70k + +### 3. 工具替换 +mgrep 替代 grep/ripgrep，在 50 任务 benchmark 中减少约 2x token 使用。 + +### 4. 代码模块化 +文件保持 200-400 行（最大 800）。模块化代码库让 agent 不需要读取大文件，减少上下文消耗，且首次成功率更高。 + +## 配置 + +```json +{ + "model": "sonnet", + "env": { + "MAX_THINKING_TOKENS": "10000", + "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "50" + } +} +``` + +## Skill 的渐进式加载 + +Skill 启动时只读描述（约 100 tokens），只在相关时才加载完整内容。这比把所有内容放在 CLAUDE.md 系统提示中高效得多。 + +--- + +## Related + +- [[Everything Claude Code 最佳实践]] +- [[Everything Claude Code Agent 编排模式]] diff --git a/6 - Zettelkasten/20260308221500 Everything Claude Code 多服务编排详解.md b/6 - Zettelkasten/20260308221500 Everything Claude Code 多服务编排详解.md new file mode 100644 index 0000000..d050557 --- /dev/null +++ b/6 - Zettelkasten/20260308221500 Everything Claude Code 多服务编排详解.md @@ -0,0 +1,586 @@ +--- +created: "2026-03-08 22:15" +type: zettel +tags: [claude-code, multi-agent, orchestration, workflow] +source: "https://github.com/affaan-m/everything-claude-code" +--- + +# Everything Claude Code 多服务编排详解 + +ECC 的多服务编排分为两个层次，对应不同命令，加上社区总结的实战模式。 + +--- + +## 层次 1：/orchestrate — 单模型多 Agent 流水线 + +核心思路：把一个复杂任务拆成多个阶段，每个阶段由不同专用 Agent 处理，通过 Handoff 文档传递上下文。 + +### 4 种预设工作流 + +| 类型 | Agent 链 | 适用场景 | +|------|----------|----------| +| `feature` | planner → tdd-guide → code-reviewer → security-reviewer | 新功能开发全流程 | +| `bugfix` | planner → tdd-guide → code-reviewer | Bug 调查与修复 | +| `refactor` | architect → code-reviewer → tdd-guide | 安全重构 | +| `security` | security-reviewer → code-reviewer → architect | 安全专项审查 | + +### 用法 + +```bash +# 完整功能开发流水线 +/orchestrate feature "添加用户认证系统" + +# 自定义 Agent 链 +/orchestrate custom "architect,tdd-guide,code-reviewer" "重新设计缓存层" +``` + +### 执行过程 + +1. Planner 分析需求 → 生成 Handoff 文档 +2. TDD Guide 读取 Handoff → 先写测试再实现 → 生成新 Handoff +3. Code Reviewer 审查 → 发现问题 → 传递给下一个 +4. Security Reviewer 安全审计 → 最终报告 (SHIP / NEEDS WORK / BLOCKED) + +独立阶段可以并行执行（如 code-reviewer + security-reviewer + architect 同时跑）。 + +### Handoff 文档格式 + +```markdown +## HANDOFF: [previous-agent] -> [next-agent] +### Context — 做了什么 +### Findings — 关键发现或决策 +### Files Modified — 修改的文件 +### Open Questions — 未解决的问题 +### Recommendations — 建议的下一步 +``` + +--- + +## 层次 2：/multi-workflow — 多模型协作 6 阶段流水线 + +核心思路：Claude 作为编排者（Orchestrator），调度 Codex（后端权威）和 Gemini（前端权威）并行工作，最终由 Claude 综合并实施。 + +### 6 个阶段 + +``` +Research → Ideation → Plan → Execute → Optimize → Review +``` + +| 阶段 | 做什么 | 谁来做 | +|------|--------|--------| +| 1. Research | 需求理解、上下文收集、打分(0-10) | Claude + MCP | +| 2. Ideation | 技术可行性分析、方案对比 | Codex + Gemini 并行 | +| 3. Plan | 后端架构 + 前端架构分别规划 | Codex + Gemini 并行 | +| 4. Execute | 按计划写代码 | Claude（唯一写代码的） | +| 5. Optimize | 安全/性能/可访问性审查 | Codex + Gemini 并行 | +| 6. Review | 最终验证，对照计划检查完成度 | Claude | + +### 关键规则 + +- **Code Sovereignty**：只有 Claude 能写文件，Codex/Gemini 只输出 Unified Diff（"脏原型"） +- **Trust Rules**：后端听 Codex，前端听 Gemini +- **每阶段评分 < 7 分自动停止**，要求用户确认后才继续 +- **Session 复用**：每次调用返回 SESSION_ID，后续阶段用 `resume` 保持上下文 + +### 用法 + +```bash +/multi-workflow 开发一个实时聊天功能，包含 WebSocket 后端和 React 前端 +``` + +--- + +## 多实例 vs 单实例：两种并行模型 + +编排的底层机制有本质区别，选错方式会浪费 token 或产生文件冲突。 + +### 模型对比 + +| | 多实例（Agent Teams / 多终端） | 单实例（Subagent / /orchestrate） | +|---|---|---| +| 进程数 | N 个独立 Claude Code 进程 | 1 个主进程 | +| Context | 每个独立 context window | 共享主进程 context | +| Token 消耗 | 3-7 倍 | 1-2 倍 | +| 文件协调 | git 自动合并 / worktree 隔离 | 主进程统一写入，无冲突 | +| 适合场景 | 大项目、多模块并行开发 | 单功能、流水线审查 | +| 通信方式 | git commit + 共享文档 | Handoff 文档 + 内存传递 | + +### 多实例方式 1：Agent Teams（官方实验功能） + +一个 Team Lead 进程自动 spawn 多个 Teammate 子进程： +- 每个 Teammate 在独立 context window 中工作 +- 通过 git 自动协调：认领任务、合并变更、解决冲突 +- 需要启用 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` +- Teammate 通常 20-30 秒内启动，1 分钟内开始产出 + +### 多实例方式 2：多终端手动运行 + +``` +终端 1: claude → 后端架构 +终端 2: claude → 数据库设计 +终端 3: claude → 前端开发 +终端 4: claude → 测试 +``` + +- 每个终端是一个独立 Claude Code 实例 +- 人工协调（通过共享 Plan 文件） +- 用 `claude --worktree` 让每个实例在独立 git worktree 中工作，避免文件冲突 + +### 单实例方式：Subagent（/orchestrate 和 Agent tool） + +`/orchestrate` 在一个主进程内启动子代理： +- 子代理共享同一个会话，各自独立执行 +- 主进程统一控制文件写入，不会冲突 +- 通过 Handoff 文档在 Agent 间传递上下文 +- 独立的子任务可并行（`run_in_background: true`） + +### 选择决策 + +``` +项目规模？ +├── 小功能（1-3 文件）→ 单实例 /orchestrate feature +├── 中型功能（5-10 文件）→ 单实例 /orchestrate custom（多 Agent 链） +├── 大型模块（10+ 文件）→ 多实例 Agent Teams 或多终端 +└── 全栈项目（多模块）→ 多实例 + 文件所有权分配 +``` + +--- + +## 层次 3：社区实战模式 + +### 多 Agent 并行调查（Bug Hunt） + +启动 5 个 Agent 分别调查不同假设： +- log-analyst: 分析日志模式 +- code-archaeologist: 追溯 git 历史 +- reproducer: 尝试复现 +- db-detective: 检查数据库状态 +- network-inspector: 抓包分析 + +让它们互相"辩论"，交叉验证结论。 + +### 全栈 7+ Agent 生产级编排 + +将一个全栈项目拆成 7 个专职 Agent，按依赖关系分 4 个阶段执行，能并行的并行，有依赖的串行。 + +#### 7 个 Agent 角色定义 + +| Agent | 职责 | 对应 ECC Agent | 输出物 | +|-------|------|---------------|--------| +| backend-architect | 后端架构：API 设计、服务分层、中间件、错误处理 | architect + planner | API 契约文档、路由定义、Service 接口 | +| database-architect | 数据库架构：Schema 设计、索引、迁移、RLS | database-reviewer | DDL 迁移文件、ER 图、索引策略 | +| frontend-developer | 前端实现：组件、状态管理、路由、UI/UX | code-reviewer (前端) | React/Vue 组件、页面、样式 | +| test-automator | 自动化测试：单元 + 集成 + E2E | tdd-guide + e2e-runner | 测试文件、覆盖率报告 | +| security-auditor | 安全审计：OWASP Top 10、secrets、注入防护 | security-reviewer | 安全报告、修复补丁 | +| deployment-engineer | 部署：Docker、CI/CD、环境配置 | (自定义) | Dockerfile、GitHub Actions、部署脚本 | +| observability-engineer | 可观测性：日志、监控、告警、tracing | (自定义) | 日志配置、Prometheus metrics、告警规则 | + +#### 4 阶段执行流程 + +``` +阶段 1 (并行) 阶段 2 (串行) 阶段 3 (串行) 阶段 4 (并行) +┌──────────────┐ ┌───────────────────┐ ┌──────────────┐ ┌─────────────────────┐ +│ backend- │ │ │ │ │ │ security-auditor │ +│ architect │──│ frontend- │──│ test- │──│ deployment-engineer │ +│ │ │ developer │ │ automator │ │ observability- │ +│ database- │ │ (依赖后端API契约) │ │ (依赖实现代码)│ │ engineer │ +│ architect │ │ │ │ │ │ (三者可并行) │ +└──────────────┘ └───────────────────┘ └──────────────┘ └─────────────────────┘ +``` + +**阶段 1：架构设计（并行）** +- backend-architect 和 database-architect 同时工作 +- backend-architect 输出 API 契约（RESTful 路由、请求/响应类型、中间件链） +- database-architect 输出 Schema DDL、索引策略、RLS 策略 +- 两者通过共享的数据模型文档协调 +- 产出：`HANDOFF: architects -> frontend-developer` + +**阶段 2：前端实现（串行）** +- 依赖阶段 1 的 API 契约和数据模型 +- frontend-developer 基于 API 契约生成类型定义和 API client +- 实现页面组件、状态管理、路由 +- 产出：`HANDOFF: frontend-developer -> test-automator` + +**阶段 3：测试（串行）** +- 依赖阶段 1+2 的全部实现代码 +- 写单元测试（后端 Service、前端组件） +- 写集成测试（API 端点 + 数据库） +- 写 E2E 测试（关键用户流程） +- 验证覆盖率 >= 80% +- 产出：`HANDOFF: test-automator -> final-review` + +**阶段 4：交付保障（并行）** +- security-auditor：OWASP Top 10 扫描、secrets 检测、依赖漏洞审计 +- deployment-engineer：编写 Dockerfile、CI/CD pipeline、环境变量管理 +- observability-engineer：配置结构化日志、metrics endpoint、告警规则 +- 三者独立，可完全并行 + +#### 实际实现方式 + +**方式 A：用 /orchestrate custom** + +```bash +# 阶段 1：并行架构设计 +/orchestrate custom "architect,database-reviewer" "设计电商平台后端架构和数据库 Schema" + +# 阶段 2：前端开发 +/orchestrate custom "planner,tdd-guide,code-reviewer" "基于 API 契约实现 React 前端" + +# 阶段 3+4：测试 + 安全 + 部署 +/orchestrate custom "tdd-guide,e2e-runner,security-reviewer" "编写测试套件并进行安全审计" +``` + +**方式 B：用 Agent Teams（实验性功能）** + +```bash +# 启用 Agent Teams +# 在 settings.json 中设置 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS + +# Team Lead 自动协调，启动多个 teammate +# 每个 teammate 在独立 context window 中工作 +# 通过 git 自动协调文件修改 +``` + +**方式 C：多终端手动编排** + +``` +终端 1 (Team Lead): 协调、规划、合并结果 +终端 2 (Backend): 后端架构 + API 实现 +终端 3 (Database): Schema + 迁移 + 索引 +终端 4 (Frontend): 组件 + 页面 + 状态管理 +终端 5 (Testing): 测试编写 + 覆盖率验证 +``` + +#### 关键协调机制 + +**文件所有权**：每个 Agent 拥有不同的文件集，避免冲突 +``` +backend-architect: src/api/**, src/services/**, src/middleware/** +database-architect: src/db/**, migrations/**, prisma/** +frontend-developer: src/components/**, src/pages/**, src/hooks/** +test-automator: tests/**, e2e/**, __tests__/** +security-auditor: 只读审计，不直接改文件 +deployment-engineer: Dockerfile, .github/**, docker-compose.yml +observability-engineer: src/logging/**, src/metrics/**, alerting/** +``` + +**Handoff 文档**：每个阶段结束后生成结构化交接文档，包含上下文、发现、修改文件、未解决问题、建议。 + +**Git Worktree 隔离**：每个 Agent 在独立 worktree 中工作，最后由 Team Lead 合并。 + +#### 实际注意事项 + +- Token 消耗：7 个 Agent 约消耗单 Agent 的 5-7 倍 token +- 起步建议：先用 3-4 个核心 Agent（architect + tdd-guide + code-reviewer + security-reviewer），稳定后再扩展 +- 协调开销：超过 4-5 个 Agent 后，协调成本开始上升，需权衡 +- 适用规模：中大型项目（10+ 文件的功能模块），小功能用 `/orchestrate feature` 更高效 + +### 最佳实践 + +- 起步用 3-5 个 Agent，在并行效率和协调成本之间取平衡 +- Agent 间通过共享文档（Handoff / Plan 文件）通信 +- 用 git worktree 隔离不同 Agent 的工作区，避免冲突 +- 每个 Agent 拥有独立的文件集，避免同时编辑同一文件 +- 开发时间可缩减约 75%（社区用户反馈） + +--- + +## 全自动编排实操 Prompt + +两种方式实现全自动，不需要手动开关实例。 + +### 方式 1：/orchestrate custom（单实例，求稳） + +一条命令，全自动串行执行 Agent 链： + +```bash +/orchestrate custom "architect,database-reviewer,planner,tdd-guide,e2e-runner,code-reviewer,security-reviewer" " + +## 项目需求 +电商平台用户系统 + +## 功能范围 +- 用户注册/登录（JWT） +- 个人资料 CRUD +- 密码重置流程 +- 角色权限（admin/user） + +## 技术栈 +- 后端：Node.js + Express + TypeScript +- 数据库：PostgreSQL + Prisma +- 前端：React + TailwindCSS + +## 约束 +- RESTful API 设计 +- 80%+ 测试覆盖率 +- RLS 启用 +" +``` + +### 方式 2：Agent Teams（多实例，求快） + +Team Lead 自动 spawn teammate，控制阶段顺序： + +```bash +claude " +你是 Team Lead。任务：设计并实现电商平台用户系统。 + +## 技术栈 +- 后端：Node.js + Express + TypeScript +- 数据库：PostgreSQL + Prisma +- 前端：React + TailwindCSS + +## 执行计划 + +### 阶段 1（并行启动 2 个 teammate） +- teammate-1 'backend-architect': 设计 RESTful API 路由、Service 层接口、中间件链。 + 输出 API 契约文档到 docs/api-contract.md，实现 src/api/**、src/services/**、src/middleware/** +- teammate-2 'database-architect': 设计用户表 Schema，编写 Prisma migration，定义索引和 RLS。 + 输出到 prisma/**、docs/schema.md + +等待阶段 1 全部完成后继续。 + +### 阶段 2（启动 1 个 teammate） +- teammate-3 'frontend-developer': 读取 docs/api-contract.md，生成 API client 和类型。 + 实现登录、注册、个人资料、密码重置页面。输出到 src/components/**、src/pages/**、src/hooks/** + +等待阶段 2 完成后继续。 + +### 阶段 3（启动 1 个 teammate） +- teammate-4 'test-automator': 单元测试覆盖 Service 层，集成测试覆盖 API 端点， + E2E 测试覆盖注册→登录→修改资料流程。覆盖率 >= 80%。输出到 tests/**、e2e/** + +等待阶段 3 完成后继续。 + +### 阶段 4（并行启动 2 个 teammate） +- teammate-5 'security-auditor': 审计全部代码，OWASP Top 10 + secrets 检测。 + 输出到 docs/security-report.md +- teammate-6 'deployment-engineer': Dockerfile、docker-compose.yml、GitHub Actions。 + 输出到 .github/workflows/**、Dockerfile + +## 文件所有权（避免冲突） +- teammate-1: src/api/**, src/services/**, src/middleware/** +- teammate-2: prisma/**, docs/schema.md +- teammate-3: src/components/**, src/pages/**, src/hooks/**, src/lib/api-client.ts +- teammate-4: tests/**, e2e/** +- teammate-5: docs/security-report.md（只读审计） +- teammate-6: Dockerfile, docker-compose.yml, .github/** + +## 规则 +- 每个阶段必须等前一阶段全部完成 +- 每个 teammate 只修改自己负责的文件 +- 发现阻塞性问题立即报告，不要猜测 +" +``` + +### Prompt 写作要点 + +| 要素 | 为什么重要 | +|------|-----------| +| 功能范围 | 明确边界，防止 Agent 做多余的事 | +| 技术栈 | 避免 Agent 自行选型产生冲突 | +| 阶段划分 + 等待指令 | 控制串行/并行顺序 | +| 文件所有权 | 防止多 Agent 同时改同一文件 | +| 输出物路径 | 让下游 Agent 知道去哪里读上游产出 | +| 约束条件 | 覆盖率、安全标准等硬性要求 | + +### 两种方式对比 + +| | /orchestrate custom | Agent Teams | +|---|---|---| +| 自动化程度 | 全自动 | 全自动 | +| 并行能力 | 有限（子代理级） | 真并行（多进程） | +| 速度 | 串行为主，较慢 | 并行阶段快 3-5 倍 | +| Token 消耗 | 1-2 倍 | 3-7 倍 | +| 稳定性 | 成熟稳定 | 实验性功能 | +| 上手难度 | 零配置 | 需启用实验 flag | + +--- + +## 全新项目开发策略 + +### 单个功能：直接 /orchestrate feature + +```bash +/orchestrate feature "Add JWT-based user authentication with login, register, password reset" +``` + +4 个 Agent 依次执行： + +1. **Planner** — 规划出 controller、service、middleware、routes 等文件结构 +2. **TDD Guide** — 先写 `auth.test.ts`，再写 `auth.service.ts`、`auth.controller.ts` +3. **Code Reviewer** — 检查错误处理、输入验证、代码质量 +4. **Security Reviewer** — 检查 JWT 存储、密码哈希、CSRF、rate limiting + +### 整个项目：先 /plan 拆分，再逐模块 /orchestrate + +```bash +# 第 1 步：整体规划，拆分模块 +/plan "电商平台：用户系统 + 商品管理 + 订单系统 + 支付集成" + +# 第 2 步：按模块逐个走完整流水线 +/orchestrate feature "用户注册登录系统" +/orchestrate feature "商品 CRUD 和分类管理" +/orchestrate feature "购物车和订单流程" +/orchestrate feature "支付网关集成" +``` + +### 需要架构设计时：自定义 Agent 链 + +全新项目往往需要先做架构决策，在链头加上 architect： + +```bash +/orchestrate custom "architect,planner,tdd-guide,code-reviewer,security-reviewer" "设计并实现微服务网关" +``` + +### 前后端全栈：用 /multi-workflow + +当前后端都要从头开发时，用多模型协作更高效： + +```bash +/multi-workflow "电商平台用户系统，包含 React 前端和 Node.js 后端" +``` + +Codex 负责后端架构，Gemini 负责前端设计，Claude 综合实施。 + +### 选择决策树 + +``` +全新项目？ +├── 单个功能 → /orchestrate feature +├── 多模块项目 → /plan 拆分 → 逐个 /orchestrate feature +├── 需要架构设计 → /orchestrate custom (加 architect) +└── 前后端全栈 → /multi-workflow +``` + +--- + +## 阶段追踪最佳实践 + +ECC 本身没有内建 Kanban/Sprint board，但可以组合 3 层机制实现"完成一个阶段就 mark 完成"的效果。 + +### 3 层机制 + +| 层 | 机制 | 属于 | 作用 | +|---|------|------|------| +| 1 | TaskCreate + TaskUpdate | Claude Code 原生（v2.1.16+） | 状态追踪 + 依赖关系 + 跨 session 持久化 | +| 2 | `/checkpoint` | ECC | Git 级别快照，可回滚 | +| 3 | Handoff 文档 | ECC `/orchestrate` | Agent 间上下文传递 | + +### Claude Code 原生 Tasks 系统 + +取代了旧的 TodoWrite，是最接近 Kanban 的原生机制： + +``` +TaskCreate("backend-architecture") + → TaskUpdate(status: in_progress) # 开始时标记 + → TaskUpdate(status: completed) # 完成时标记 +``` + +核心能力： +- **依赖关系**：`addBlockedBy` 让阶段 2 等阶段 1 完成 +- **跨 session 持久化**：context 压缩后 task 状态不丢 +- **跨实例共享**：设置 `CLAUDE_CODE_TASK_LIST_ID` 环境变量，多个 Claude 实例看到同一个任务板 +- **3-Task 规则**：少于 3 步的直接做，不值得建 task + +### 组合实践：/orchestrate + Tasks + /checkpoint + +在 `/orchestrate` 的 prompt 中加入 Task 追踪指令： + +```bash +/orchestrate custom "architect,database-reviewer,planner,tdd-guide,code-reviewer,security-reviewer" " + +## 项目需求 +电商平台用户系统 + +## 技术栈 +Node.js + Express + TypeScript + PostgreSQL + Prisma + React + +## 阶段追踪要求 +每个 Agent 开始时： +1. TaskCreate 创建当前阶段任务 +2. TaskUpdate 标记 in_progress +3. 如果依赖前一阶段，用 addBlockedBy 关联 + +每个 Agent 完成时： +1. /checkpoint create 'phase-N-done' +2. TaskUpdate 标记 completed +3. 生成 Handoff 文档传递给下一个 Agent +" +``` + +### Agent Teams + 共享 Task Board + +多实例场景下，用共享 Task 列表实现自动阶段协调： + +```bash +# 所有实例共享同一个任务板 +export CLAUDE_CODE_TASK_LIST_ID="ecommerce-user-system" + +claude " +你是 Team Lead。 + +## 任务追踪规则 +- 用 TaskCreate 为每个阶段创建任务，带依赖关系 +- teammate 开始工作时 TaskUpdate → in_progress +- teammate 完成后 TaskUpdate → completed +- 所有 teammate 共享同一个 CLAUDE_CODE_TASK_LIST_ID +- 通过 Task 状态判断前置阶段是否完成，自动启动下一阶段 + +## 阶段依赖 +- Task: 'backend-architecture' → teammate-1 +- Task: 'database-schema' → teammate-2 +- Task: 'frontend' (blockedBy: backend-architecture, database-schema) → teammate-3 +- Task: 'testing' (blockedBy: frontend) → teammate-4 +- Task: 'security-audit' (blockedBy: testing) → teammate-5 +- Task: 'deployment' (blockedBy: testing) → teammate-6 +" +``` + +Team Lead 通过 Task 状态自动判断何时启动下一阶段，不需要人工干预。 + +### 追踪机制选择 + +| 需求 | 用什么 | +|------|--------| +| 阶段状态（pending/in_progress/completed） | TaskCreate + TaskUpdate（原生） | +| 阶段间依赖 | addBlockedBy（原生） | +| 多实例共享进度 | CLAUDE_CODE_TASK_LIST_ID（原生） | +| Git 级别快照回滚 | `/checkpoint`（ECC） | +| Agent 间上下文传递 | Handoff 文档（ECC `/orchestrate`） | +| 自主循环 + 质量门禁 | `/loop-start` + `/quality-gate`（ECC） | +| 完整 Kanban 3 文件看板 | planning-with-files（第三方插件，非 ECC） | + +--- + +## 命令选择速查 + +| 场景 | 用哪个 | +|------|--------| +| 单个功能从规划到上线 | `/orchestrate feature` | +| 修 Bug 全流程 | `/orchestrate bugfix` | +| 安全重构 | `/orchestrate refactor` | +| 前后端都要改，多 AI 协作 | `/multi-workflow` | +| 只要多模型并行出方案 | `/multi-plan` | +| 只要多模型并行写代码 | `/multi-execute` | + +--- + +## Related + +- [[Everything Claude Code 用法速查]] +- [[Everything Claude Code Agent 编排模式]] +- [[Everything Claude Code 完整指南]] + +## Source + +- [Claude Code Task Management 原生指南](https://claudefa.st/blog/guide/development/task-management) +- [Claude Code Tasks 更新公告](https://venturebeat.com/orchestration/claude-codes-tasks-update-lets-agents-work-longer-and-coordinate-across) +- [Claude Code Checkpointing 官方文档](https://code.claude.com/docs/en/checkpointing) +- [Claude Code Agent Teams 官方文档](https://code.claude.com/docs/en/agent-teams) +- [Claude Code 多 Agent 编排完整指南 2026](https://www.eesel.ai/blog/claude-code-multiple-agent-systems-complete-2026-guide) +- [Shipyard: Multi-agent orchestration](https://shipyard.build/blog/claude-code-multi-agent/) +- [10+ Claude 实例并行编排实战](https://dev.to/bredmond1019/multi-agent-orchestration-running-10-claude-instances-in-parallel-part-3-29da) +- [Claude Code Swarm 编排 Skill](https://gist.github.com/kieranklaassen/4f2aba89594a4aea4ad64d753984b2ea) +- [Ruflo: Agent 编排平台](https://github.com/ruvnet/ruflo) +- [Claude Code Workflow 框架](https://github.com/catlog22/Claude-Code-Workflow) diff --git a/6 - Zettelkasten/20260308223000 Claude Code Memory 日常最佳实践.md b/6 - Zettelkasten/20260308223000 Claude Code Memory 日常最佳实践.md new file mode 100644 index 0000000..dd6b8d4 --- /dev/null +++ b/6 - Zettelkasten/20260308223000 Claude Code Memory 日常最佳实践.md @@ -0,0 +1,192 @@ +--- +created: "2026-03-08 23:30" +type: zettel +tags: [claude-code, memory, persistence, workflow, best-practice] +source: "daily usage + ECC documentation" +--- + +# Claude Code Memory 日常最佳实践 + +Claude Code 有 5 层 memory 机制，从自动到手动，每层解决不同问题。 + +--- + +## 5 层 Memory 全景 + +``` +层 1: CLAUDE.md (全局人设，每次会话自动加载) +层 2: Auto Memory (~/.claude/projects/*/memory/) ← 最有用 +层 3: Session Persistence (~/.claude/sessions/) ← 自动运行 +层 4: Instincts (~/.claude/homunculus/instincts/) ← 自动学习 +层 5: Project CLAUDE.md (项目根目录) ← 团队共享 +``` + +--- + +## 层 1：~/.claude/CLAUDE.md — 全局人设 + +每次会话自动加载。放什么： +- 个人偏好（no emoji、文件大小限制、commit 格式） +- 技术栈声明（Python, C#/.NET, Java, TypeScript） +- 工作流规则的索引（指向 rules/ 而不是重复内容） + +不放什么： +- 具体项目细节（放项目 CLAUDE.md） +- 临时任务状态（放 Auto Memory） +- 技术文档（放 rules/ 或 skills/） + +保持简洁（30 行左右），越短 = 每次加载消耗越少 token。 + +--- + +## 层 2：Auto Memory — 项目级持久记忆 + +位置：`~/.claude/projects//memory/` + +### MEMORY.md 结构模板 + +```markdown +# 项目名 - Memory Index +> MEMORY.md = index (always loaded, max 200 lines). Details in topic files. + +## Environment +- 运行环境、依赖版本、特殊配置 + +## Key Architecture +- 核心目录结构、关键文件路径 +- See [architecture.md](architecture.md) for details + +## Workflow Rules +- 这个项目的开发流程 + +## Active Session State +**Task**: 当前任务描述 +**Status**: in_progress / complete +**Plan file**: 计划文件路径 + +## Known Issues +- 已知的坑、预期的测试失败、临时 workaround + +## Topic Files +- [architecture.md](architecture.md) +- [test-locations.md](test-locations.md) +- [debugging.md](debugging.md) +``` + +### 关键规则 + +- MEMORY.md 超过 200 行会被截断，保持它是**索引**而不是详情 +- 详情拆到 topic file，从 MEMORY.md 链接过去 +- 只存**稳定模式**，不存临时信息 +- topic file 按主题组织（architecture、debugging、config、test-locations） + +--- + +## 层 3：Session Persistence — 会话自动摘要 + +位置：`~/.claude/sessions/` + +ECC hook 自动运行： +- 会话开始 → 自动加载最近 7 天的 session 文件 +- 会话结束 → 自动保存摘要（任务、修改文件、使用工具） + +日常操作： +```bash +/sessions list # 查看历史 +/sessions load 2026-03-08 # 加载特定会话 +/sessions alias 2026-03-08 "stock-api" # 起别名 +/sessions load stock-api # 用别名加载 +``` + +不需要手动操心，hook 负责自动创建和更新。 + +--- + +## 层 4：Instincts — 自动学习行为模式 + +位置：`~/.claude/homunculus/instincts/personal/` + +ECC continuous-learning-v2 hook 在后台观察操作，自动提取模式： +- 你纠正 Claude → 学到 instinct +- 你反复用某种模式 → 学到 instinct +- instinct 有置信度分数（0.3 → 0.9 逐步提升） + +日常操作： +```bash +/instinct-status # 查看已学习的 instinct +/instinct-export # 导出给队友 +/instinct-import # 导入其他项目的 +/promote # 项目 instinct → 全局 +``` + +手动告诉 Claude 记住偏好： +``` +"记住：这个项目用 pnpm 而不是 npm" +"记住：Billo 项目的所有 API 都要加 correlation-id" +``` + +--- + +## 层 5：项目 CLAUDE.md vs Auto Memory + +| | 项目 CLAUDE.md | Auto Memory | +|---|---|---| +| 位置 | 项目根目录（git 跟踪） | ~/.claude/projects/（本地） | +| 团队共享 | 是（提交到 git） | 否（个人） | +| 内容 | 项目规范、命令、架构说明 | 个人经验、调试记录、任务状态 | +| 修改频率 | 低（稳定后很少改） | 高（每次会话可能更新） | + +--- + +## 日常工作流 + +### 开始新项目 + +1. 创建项目 CLAUDE.md（团队共享的规范） +2. Auto Memory 自动创建 memory/ 目录 +3. 首次会话后 MEMORY.md 开始积累 +4. 遇到项目特有模式 → 写入 topic file + +### 继续昨天的工作 + +1. 打开 Claude Code → 自动加载 MEMORY.md + 最近 session +2. Claude 通过 Active Session State 知道你做到哪了 +3. 继续工作 +4. 完成后更新 MEMORY.md 状态 + +### 切换项目 + +1. cd 到另一个项目 +2. Claude 自动加载那个项目的 CLAUDE.md + MEMORY.md +3. 上下文完全切换，不会混淆 + +### 发现通用模式 + +1. 在项目 A 发现好用模式 +2. "记住：所有 API 都要用 Result pattern" +3. instinct 保存到项目级 +4. 在项目 B 也验证了 → `/promote` 提升为全局 + +### Debug 经验保存 + +``` +你："把这次 debug 经验保存到 memory" +Claude → 写入 memory/debugging.md +Claude → 更新 MEMORY.md 索引 +下次遇到类似问题 → Claude 自动读到这个经验 +``` + +--- + +## Related + +- [[Everything Claude Code 多服务编排详解]] +- [[Everything Claude Code 用法速查]] +- [[Everything Claude Code 完整指南]] + +## Source + +- [Claude Code 官方文档](https://code.claude.com/docs/en/how-claude-code-works) +- [Claude Code Task Management](https://claudefa.st/blog/guide/development/task-management) +- ECC hooks: session-start.js, session-end.js, observe.sh +- ECC skills: continuous-learning-v2, strategic-compact diff --git a/README.md b/README.md index 8be0d61..bd5ac47 100644 --- a/README.md +++ b/README.md @@ -154,6 +154,76 @@ MOC（Map of Content）是主题索引笔记，当某个领域的笔记积累到 MOC 不是死板的目录，而是你对某个领域理解的地图，随时可以重新组织。 +## Claude Code 集成 + +本知识库配置了 `knowledge-vault` skill，可以在 Claude Code 中直接管理笔记。 + +### 快捷命令 + +| 命令 | 作用 | +|------|------| +| "新建笔记 [内容]" | 在 `1 - Inbox/` 创建 Inbox 笔记 | +| "新建日记" | 在 `0 - Daily Notes/` 创建今天的日记 | +| "新建卡片 [想法]" | 在 `6 - Zettelkasten/` 创建原子笔记 | +| "整理收件箱" | 审查并整理 `1 - Inbox/` 中的笔记 | +| "搜索 [关键词]" | 搜索所有笔记 | +| "找关联" | 查找相关笔记并建议链接 | +| "健康检查" | 检查孤立笔记、缺失标签，建议连接 | + +### 最佳实践 + +#### 1. 阅读后提炼卡片 + +读完文章、文档或技术博客后，把链接或内容丢给 Claude： + +``` +读一下这篇文章 [URL]，帮我提炼出 2-3 个值得记录的 Zettelkasten 卡片 +``` + +Claude 会自动生成格式正确的原子笔记，包括 tags、source 和 related links。 + +#### 2. 工作中沉淀知识 + +用 Claude 解决技术问题后，直接说： + +``` +把今天解决的 [问题描述] 记录成一张卡片 +``` + +工作中踩过的坑会自动变成知识库资产，下次遇到类似问题能搜到。 + +#### 3. 知识检索与综合 + +需要调研某个话题时： + +``` +搜索所有关于 "微服务" 的笔记，帮我综合一下我目前的理解 +``` + +Claude 能跨笔记综合内容、发现矛盾、指出知识缺口。 + +#### 4. 定期维护 + +``` +整理收件箱 → 每周，Claude 逐条分析 Inbox 笔记并建议分类 +健康检查 → 每月，扫描孤立笔记、缺失标签，建议新连接 +``` + +### 推荐工作流 + +``` +日常工作（Claude Code） + ↓ 解决了问题 / 学到了东西 +"新建卡片 [洞察]" + ↓ 自动写入 6 - Zettelkasten +每周："整理收件箱" + ↓ Claude 帮你分类 +每月："健康检查" + ↓ 修复孤立笔记，补充链接 +``` + +核心思路：让 Claude 承担知识管理的"体力活"（格式化、分类、找关联），你只负责思考和判断。 + ## 进阶建议 随着笔记增多，可以逐步引入：