kai/knowledge-base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Sync

Browse Source
This commit is contained in:
Yaojia Wang
2026-03-14 20:23:32 +01:00
parent 50d7d1de3d
commit ad79665527
13 changed files with 2724 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

302
2 - Projects/PVE Security Scanner.md Normal file
View File

@@ -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 <target>` |
| **Nuclei** | 快速漏洞扫描 (模板驱动, SHA256 校验) | `nuclei -u <url>` |
| **httpx** | HTTP 探测、服务识别 (SHA256 校验) | `httpx -l hosts.txt` |
| **Nikto** | Web 服务器扫描 | `nikto -h <url>` |
| **testssl.sh** | TLS/SSL 安全检测 | `testssl <host:port>` |
| **NetExec** | SMB/RDP/WinRM 评估 | `netexec smb <target>` |
## 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/<timestamp>/`
### 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=<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]]

266
4 - Resources/Everything Claude Code 完整指南.md Normal file
View File

@@ -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)

182
4 - Resources/Everything Claude Code 用法速查.md Normal file
View File

@@ -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)

326
4 - Resources/HomeLab Infrastructure.md Normal file
View File

@@ -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]]

140
4 - Resources/OpenBB Invest API - K8s Infrastructure.md Normal file
View File

@@ -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]]

111
4 - Resources/OpenClaw-Skill-Reference.md Normal file
View File

@@ -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 <method>`
- **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 工具链]]

403
4 - Resources/OpenVAS Usage Guide.md Normal file
View File

@@ -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=<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 <PASSWORD> \
socket --socketpath /run/gvmd/gvmd.sock \
--xml '<get_tasks/>'
# 列出所有 target
gvm-cli --gmp-username admin --gmp-password <PASSWORD> \
socket --socketpath /run/gvmd/gvmd.sock \
--xml '<get_targets/>'
```
## 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 <service>` 查看错误 |
| 磁盘空间不足 | `df -h` 检查；清理旧报告和 Docker 无用镜像 `sudo docker system prune` |
## Related
- [[PVE Security Scanner]] - 部署文档和安全架构
- [[Security Best Practices]]

47
6 - Zettelkasten/20260308213000 Everything Claude Code 最佳实践.md Normal file
View File

@@ -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 优化]]

52
6 - Zettelkasten/20260308213100 Everything Claude Code Agent 编排模式.md Normal file
View File

@@ -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 完整指南]]

47
6 - Zettelkasten/20260308213200 Everything Claude Code Token 优化.md Normal file
View File

@@ -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 编排模式]]

586
6 - Zettelkasten/20260308221500 Everything Claude Code 多服务编排详解.md Normal file
View File

@@ -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)

192
6 - Zettelkasten/20260308223000 Claude Code Memory 日常最佳实践.md Normal file
View File

@@ -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/<project-hash>/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

70
README.md
View File

@@ -154,6 +154,76 @@ MOC（Map of Content）是主题索引笔记，当某个领域的笔记积累到
MOC 不是死板的目录，而是你对某个领域理解的地图，随时可以重新组织。 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 承担知识管理的"体力活"（格式化、分类、找关联），你只负责思考和判断。
## 进阶建议 ## 进阶建议
随着笔记增多，可以逐步引入： 随着笔记增多，可以逐步引入：