Develata's Space - Knowledge

CLIProxyAPI

Wed, 13 May 2026 00:00:00 GMT

CLIProxyAPI 使用指南

1. CLIProxyAPI 是什么

CLIProxyAPI 是把 Gemini CLI、Antigravity、ChatGPT Codex、Claude Code 等 CLI / OAuth 账号封装成 OpenAI / Gemini / Claude / Codex 兼容 API 的代理服务。

CLI / OAuth 账号
    ↓
CLIProxyAPI
    ↓
OpenAI-compatible / Gemini / Claude / Codex API

官方文档：

截至 2026-05-13，官方 README 明确写出 CLIProxyAPI 支持 Codex、Claude Code、Gemini CLI、Antigravity 等 OAuth / CLI 来源，并提供 OpenAI / Gemini / Claude / Codex compatible API。官方支持 Docker / Docker Compose，但低配 VPS 更适合预编译二进制 + systemd。

2. 推荐架构

Docker Compose 模板：

CLIProxyAPI Docker Compose

本文主推二进制部署：

客户端
    ↓
https://cliproxyapi.example.com/v1
    ↓
Nginx 443
    ↓
127.0.0.1:8317
    ↓
CLIProxyAPI
    ↓
Codex / ChatGPT OAuth

原则：

CLIProxyAPI 只监听 127.0.0.1:8317
公网只暴露 Nginx 80/443
/v1/* 不加 Nginx Basic Auth，只用 CLIProxyAPI 的 Bearer API key
默认关闭管理面板
如果打开管理面板，只给 /management.html 单独加 Basic Auth

3. 安装

基础工具：

sudo apt update
sudo apt install -y curl wget ca-certificates tar openssl nginx certbot python3-certbot-nginx

1C1G VPS 建议加 2G swap；已有 swap 跳过：

free -h
swapon --show

sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

确认架构：

uname -m

x86_64 用 amd64 包：

cd /tmp

rm -f cli-proxy-api
rm -f CLIProxyAPI_*_linux_amd64.tar.gz

VERSION=$(curl -s https://api.github.com/repos/router-for-me/CLIProxyAPI/releases/latest \
  | grep tag_name \
  | cut -d '"' -f 4)
VERSION_NO_V="${VERSION#v}"

echo "VERSION=$VERSION"
echo "VERSION_NO_V=$VERSION_NO_V"

wget -O "CLIProxyAPI_${VERSION_NO_V}_linux_amd64.tar.gz" \
  "https://github.com/router-for-me/CLIProxyAPI/releases/download/${VERSION}/CLIProxyAPI_${VERSION_NO_V}_linux_amd64.tar.gz"

tar -xzf "CLIProxyAPI_${VERSION_NO_V}_linux_amd64.tar.gz"
chmod +x cli-proxy-api
sudo install -m 755 cli-proxy-api /usr/local/bin/cli-proxy-api

验证：

which cli-proxy-api
cli-proxy-api -h

如果 which 没输出：

/usr/local/bin/cli-proxy-api -h

如果不是 x86_64，按 GitHub Release assets 替换对应架构包。

4. 配置

创建目录并生成 API key：

mkdir -p "$HOME/.cli-proxy-api/logs"
API_KEY=$(openssl rand -hex 32)
echo "$API_KEY"

写入 ~/.cli-proxy-api/config.yaml：

cat > "$HOME/.cli-proxy-api/config.yaml" <


查看配置：
cat "$HOME/.cli-proxy-api/config.yaml"

说明：

host: "127.0.0.1"：只允许本机访问
auth-dir：保存 OAuth 凭据
api-keys：客户端 Bearer API key
disable-control-panel: true：关闭内置管理页
commercial-mode: true：降低高并发下的中间件开销


5. Codex 登录
cli-proxy-api -config "$HOME/.cli-proxy-api/config.yaml" -codex-device-login

按提示在浏览器登录 OpenAI / ChatGPT 账号并输入 code。成功后应出现类似文件：
~/.cli-proxy-api/codex-xxxx.json


6. 前台测试
启动：
cli-proxy-api -config "$HOME/.cli-proxy-api/config.yaml"

另开 SSH 窗口检查监听：
ss -lntp | grep 8317

应为：
127.0.0.1:8317

取 API key：
API_KEY=$(grep -A1 "api-keys:" ~/.cli-proxy-api/config.yaml | tail -n1 | sed 's/^[[:space:]]*- //; s/"//g')

测试：
curl -i http://127.0.0.1:8317/v1/models \
  -H "Authorization: Bearer $API_KEY"

curl http://127.0.0.1:8317/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4",
    "messages": [
      {"role": "user", "content": "Hello"}
    ],
    "stream": false
  }'

模型名以 /v1/models 返回为准。/health 返回 404 不代表服务失败。

7. systemd 常驻
把 deve 改成实际用户名：
sudo tee /etc/systemd/system/cli-proxy-api.service > /dev/null <<'EOF'
[Unit]
Description=CLI Proxy API
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=deve
WorkingDirectory=/home/deve
ExecStart=/usr/local/bin/cli-proxy-api -config /home/deve/.cli-proxy-api/config.yaml
Restart=always
RestartSec=5
Environment=HOME=/home/deve

StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target
EOF

如果用户名是 ubuntu，同步修改：
User=ubuntu
WorkingDirectory=/home/ubuntu
ExecStart=/usr/local/bin/cli-proxy-api -config /home/ubuntu/.cli-proxy-api/config.yaml
Environment=HOME=/home/ubuntu

启动：
sudo systemctl daemon-reload
sudo systemctl enable --now cli-proxy-api
sudo systemctl status cli-proxy-api

日志：
journalctl -u cli-proxy-api -f

确认监听：
ss -lntp | grep 8317

仍应是：
127.0.0.1:8317


8. Nginx + HTTPS
把 cliproxyapi.example.com 改成实际域名：
sudo tee /etc/nginx/sites-available/cliproxyapi > /dev/null <<'EOF'
server {
    listen 80;
    server_name cliproxyapi.example.com;

    client_max_body_size 100m;

    location / {
        proxy_pass http://127.0.0.1:8317;
        proxy_http_version 1.1;

        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        proxy_buffering off;
        proxy_request_buffering off;

        proxy_read_timeout 3600s;
        proxy_send_timeout 3600s;
    }
}
EOF

sudo ln -sf /etc/nginx/sites-available/cliproxyapi /etc/nginx/sites-enabled/cliproxyapi
sudo nginx -t
sudo systemctl reload nginx

如果默认站点干扰：
sudo rm -f /etc/nginx/sites-enabled/default
sudo nginx -t
sudo systemctl reload nginx

申请证书：
sudo certbot --nginx -d cliproxyapi.example.com
sudo nginx -t
sudo systemctl reload nginx

续签检查：
systemctl list-timers | grep certbot
sudo certbot renew --dry-run
sudo certbot certificates

公网测试：
curl -i https://cliproxyapi.example.com/v1/models \
  -H "Authorization: Bearer $API_KEY"

成功标准：
HTTP/2 200
content-type: application/json


9. 客户端填写
OpenAI-compatible 客户端：
Base URL: https://cliproxyapi.example.com/v1
API Key: config.yaml 里的 api-keys

不要把 /chat/completions 写进 Base URL。

10. 管理页与 Basic Auth
默认关闭管理页：
remote-management:
  allow-remote: false
  secret-key: ""
  disable-control-panel: true

这种情况下 Nginx 不需要 auth_basic，API 只靠：
Authorization: Bearer 

如果要打开管理页，只给 /management.html 加 Basic Auth：
sudo systemctl restart cli-proxy-api
sudo apt install -y apache2-utils
sudo htpasswd -c /etc/nginx/.cliproxyapi_htpasswd pwh

location = /management.html {
    auth_basic "Restricted";
    auth_basic_user_file /etc/nginx/.cliproxyapi_htpasswd;

    proxy_pass http://127.0.0.1:8317;
    proxy_http_version 1.1;

    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

不要把 auth_basic 写在 server {} 顶层，否则 /v1/models 和 /v1/chat/completions 也会被拦截。

11. 排错
11.1 命令不存在
cd /tmp
chmod +x cli-proxy-api
sudo install -m 755 cli-proxy-api /usr/local/bin/cli-proxy-api
which cli-proxy-api

11.2 Release 下载 404
当前脚本假设资产名为：
CLIProxyAPI_版本号_linux_amd64.tar.gz

如果下载失败，到 GitHub Release 页面确认实际文件名。
11.3 公网 API 返回 HTTP/2 401
如果响应头有：
www-authenticate: Basic

说明 Nginx Basic Auth 拦截了 API。检查：
sudo grep -R "auth_basic" -n /etc/nginx
sudo nginx -T | grep -n -C 5 "auth_basic"

临时删除 Basic Auth：
sudo sed -i '/auth_basic/d' /etc/nginx/sites-available/cliproxyapi
sudo nginx -t
sudo systemctl reload nginx

11.4 Nginx 修改后不生效
sudo nginx -t
sudo systemctl reload nginx


12. 备份与复刻
重点备份：
~/.cli-proxy-api/config.yaml
~/.cli-proxy-api/codex-*.json
/etc/systemd/system/cli-proxy-api.service
/etc/nginx/sites-available/cliproxyapi

复刻顺序：
安装基础工具
下载 cli-proxy-api
写 config.yaml
执行 Codex device login
配置 systemd
配置 Nginx
申请 HTTPS
用 /v1/models 测试


13. 参考链接
https://github.com/router-for-me/CLIProxyAPI
https://github.com/router-for-me/CLIProxyAPI/releases
https://github.com/router-for-me/CLIProxyAPI/blob/main/config.example.yaml
https://help.router-for.me/
https://help.router-for.me/introduction/quick-start
https://help.router-for.me/configuration/basic
https://help.router-for.me/configuration/options
https://help.router-for.me/docker/docker-compose.html



Sub2API
Wed, 13 May 2026 00:00:00 GMT
Sub2API 使用指南
1. Sub2API 是什么
Github Repo
Sub2API 是一个 AI API gateway，用于把上游账号、订阅或多模型服务统一成可管理的 API 服务。它适合放在 new-api 之前，负责上游接入、账号管理、请求转发和后台管理。
本文采用 Docker 部署：
Sub2API + PostgreSQL + Redis

如果服务器访问上游服务需要代理，可以额外加 sing-box：
Sub2API -> sing-box -> VLESS Reality -> Internet

sing-box 不是 Sub2API 的必需组件，只是本文 compose 里提供的可选出站代理。
官方文档：

https://github.com/Wei-Shaw/sub2api
https://github.com/Wei-Shaw/sub2api/blob/main/deploy/README.md
https://github.com/SagerNet/sing-box
https://sing-box.sagernet.org/installation/docker/


2. 推荐架构
配套模板：

Sub2API + sing-box Docker Compose

完整架构：
new-api
    ↓ newapi-sub2api
Sub2API
    ├── PostgreSQL
    ├── Redis
    └── sing-box，可选
            ↓
        代理节点，可选

dashboard 默认只监听：
127.0.0.1:38580

远程访问建议走 SSH 隧道，或者通过 1Panel / Nginx 加认证反代。
核心约束：

sub2api 不直接暴露公网端口
PostgreSQL / Redis 只在内部网络可见
new-api 通过 Docker 内网访问 http://sub2api:8080
需要代理时，Sub2API 出站走 sing-box
不需要代理时，删除 sing-box 相关配置即可


3. 快速部署
创建目录：
mkdir -p /opt/1panel/docker/compose/sub2api
cd /opt/1panel/docker/compose/sub2api

mkdir -p nginx sing-box sing-box-data sub2api_data postgres_data redis_data

创建 new-api 专用内网：
docker network create --driver bridge --internal newapi-sub2api

如果网络已存在，报错可以忽略。
准备文件：
docker-compose.yml
.env
nginx/default.conf
sing-box/config.json      可选，只有启用 sing-box 时需要

启动：
docker compose up -d
docker compose ps
docker compose logs -f sub2api

本机验证：
curl -v http://127.0.0.1:38580/health


4. WebUI 访问
模板通过 dashboard-proxy 把 Sub2API WebUI 绑定到宿主机本地：
127.0.0.1:38580

本地电脑访问远程服务器：
ssh -p 22 -L 38580:127.0.0.1:38580 user@你的服务器IP

然后浏览器打开：
http://127.0.0.1:38580

账号密码来自 .env：
ADMIN_EMAIL=
ADMIN_PASSWORD=

如果要用 1Panel 反代，目标写：
http://sub2api-dashboard-proxy:80

WebUI 不建议无认证直接暴露公网。

5. new-api 接入
把 new-api 容器接入同一个 Docker 内网：
docker network connect newapi-sub2api new-api

如果容器名不是 new-api，先查：
docker ps

new-api 后台上游地址：
http://sub2api:8080

测试：
docker run --rm -it \
  --network newapi-sub2api \
  curlimages/curl:latest \
  http://sub2api:8080/health


6. 出站代理，可选
如果 Sub2API 所在服务器能直连上游服务，不需要 sing-box。删除：
sing-box 服务
sub2api-proxy 网络
sub2api-egress 网络
HTTP_PROXY / HTTPS_PROXY / ALL_PROXY / UPDATE_PROXY_URL
depends_on.sing-box

如果需要代理，本文模板让 Sub2API 访问：
http://sing-box:7890

Sub2API 中的关键环境变量：
HTTP_PROXY=http://sing-box:7890
HTTPS_PROXY=http://sing-box:7890
ALL_PROXY=socks5h://sing-box:7890
NO_PROXY=localhost,127.0.0.1,::1,postgres,redis,sing-box,sub2api,new-api,newapi,*.local
UPDATE_PROXY_URL=http://sing-box:7890

NO_PROXY 必须保留内部服务名，否则 PostgreSQL、Redis、new-api 内网访问也可能被送进代理。
sing-box 使用 mixed inbound，7890 同时支持 HTTP proxy 和 SOCKS proxy。出站节点示例使用 VLESS Reality；如果你的节点不是 VLESS Reality，按实际协议修改 outbounds。

7. 数据目录
推荐目录：
/opt/1panel/docker/compose/sub2api
├── docker-compose.yml
├── .env
├── nginx/
│   └── default.conf
├── sing-box/
│   └── config.json
├── sing-box-data/
├── sub2api_data/
├── postgres_data/
└── redis_data/

重点备份：
.env
docker-compose.yml
nginx/default.conf
sub2api_data/
postgres_data/
redis_data/
sing-box/config.json      如果启用代理

迁移时不要只备份 compose 文件。

8. 常用命令
docker compose up -d
docker compose down
docker compose ps
docker compose logs -f sub2api
docker compose logs -f postgres
docker compose logs -f redis
docker compose logs -f dashboard-proxy

启用 sing-box 时：
docker compose logs -f sing-box
docker compose exec sing-box sing-box check -c /etc/sing-box/config.json

更新：
docker compose pull
docker compose up -d

备份：
cd /opt/1panel/docker/compose
tar -czf sub2api-backup-$(date +%F).tar.gz sub2api


9. 验证
验证 WebUI：
curl -v http://127.0.0.1:38580/health

验证 new-api 内网访问：
docker run --rm -it \
  --network newapi-sub2api \
  curlimages/curl:latest \
  http://sub2api:8080/health

验证代理出口：
docker exec -it sub2api sh
wget -O- https://ipinfo.io

如果返回的是代理节点出口 IP，说明 sing-box 生效。没有启用 sing-box 时，这一步应返回服务器自身出口 IP。

10. 排错
10.1 PostgreSQL 密码错误
如果 postgres_data/ 已初始化，之后修改 .env 的 POSTGRES_PASSWORD 不会自动修改数据库内部密码。
新部署可以重置：
docker compose down
rm -rf ./postgres_data ./redis_data ./sub2api_data
docker compose up -d

已有数据不要直接删目录。
10.2 Redis 认证失败
检查：
docker compose logs --tail=100 redis
docker compose logs --tail=100 sub2api

确认 .env 中 REDIS_PASSWORD 和容器环境变量一致。Redis 数据目录已存在时，也建议先确认是否有旧配置残留。
10.3 dashboard 访问不了
先在服务器上测试：
curl -v http://127.0.0.1:38580
docker logs --tail=100 sub2api-dashboard-proxy

服务器本机不通时，SSH 隧道一定不通。
10.4 new-api 访问不到 Sub2API
检查网络：
docker network inspect newapi-sub2api

确认 new-api 和 sub2api 都在该网络中，上游地址使用：
http://sub2api:8080

10.5 sing-box 启动失败
检查配置：
docker compose logs --tail=100 sing-box
docker compose run --rm sing-box check -c /etc/sing-box/config.json

常见原因：

VLESS UUID 不完整
Reality public_key / short_id 不匹配
复制了旧版 DNS 写法
复制了旧版 inbound sniff 字段


11. 参考链接
https://github.com/Wei-Shaw/sub2api
https://github.com/Wei-Shaw/sub2api/blob/main/deploy/README.md
https://github.com/SagerNet/sing-box
https://sing-box.sagernet.org/installation/docker/
https://sing-box.sagernet.org/configuration/inbound/mixed/
https://sing-box.sagernet.org/configuration/outbound/vless/




cliproxyapi
Wed, 13 May 2026 00:00:00 GMT
Github Repo
CLIProxyAPI Github Repo
官方 Docker Compose 文档：

https://help.router-for.me/docker/docker-compose.html

官方流程是克隆仓库、复制 config.example.yaml 为 config.yaml，再执行 docker compose up -d。下面是按 1Panel 风格整理后的等价模板。
docker-compose
services:
    cli-proxy-api:
        container_name: cli-proxy-api
        image: ${CLI_PROXY_IMAGE}
        restart: unless-stopped
        environment:
            - DEPLOY=${DEPLOY}
        ports:
            - ${HOST_IP}:${CLI_PROXY_API_PORT}:8317
            - ${HOST_IP}:${CLI_PROXY_MANAGEMENT_PORT}:8085
            - ${HOST_IP}:${CLI_PROXY_EXTRA_PORT_1}:1455
            - ${HOST_IP}:${CLI_PROXY_EXTRA_PORT_2}:54545
            - ${HOST_IP}:${CLI_PROXY_EXTRA_PORT_3}:51121
            - ${HOST_IP}:${CLI_PROXY_EXTRA_PORT_4}:11451
        volumes:
            - ${CLI_PROXY_CONFIG_PATH}:/CLIProxyAPI/config.yaml
            - ${CLI_PROXY_AUTH_PATH}:/root/.cli-proxy-api
            - ${CLI_PROXY_LOG_PATH}:/CLIProxyAPI/logs

env
HOST_IP=127.0.0.1

CLI_PROXY_IMAGE=eceasy/cli-proxy-api:latest

CLI_PROXY_API_PORT=8317
CLI_PROXY_MANAGEMENT_PORT=8085
CLI_PROXY_EXTRA_PORT_1=1455
CLI_PROXY_EXTRA_PORT_2=54545
CLI_PROXY_EXTRA_PORT_3=51121
CLI_PROXY_EXTRA_PORT_4=11451

CLI_PROXY_CONFIG_PATH=./config.yaml
CLI_PROXY_AUTH_PATH=./auths
CLI_PROXY_LOG_PATH=./logs

DEPLOY=

config.yaml
host: "0.0.0.0"
port: 8317

auth-dir: "/root/.cli-proxy-api"

api-keys:
    - "换成 openssl rand -hex 32 生成的强随机字符串"

debug: false
logging-to-file: false

request-retry: 2
max-retry-credentials: 0

routing:
    strategy: "round-robin"

remote-management:
    allow-remote: false
    secret-key: ""
    disable-control-panel: true

commercial-mode: true

启动：
docker compose up -d
docker compose logs -f cli-proxy-api

Codex 登录，按提示复制链接到浏览器完成登录：
docker compose exec cli-proxy-api /CLIProxyAPI/CLIProxyAPI -no-browser --codex-login

其它登录：
docker compose exec cli-proxy-api /CLIProxyAPI/CLIProxyAPI -no-browser --login
docker compose exec cli-proxy-api /CLIProxyAPI/CLIProxyAPI -no-browser --claude-login
docker compose exec cli-proxy-api /CLIProxyAPI/CLIProxyAPI -no-browser --antigravity-login

测试：
curl -i http://127.0.0.1:8317/v1/models \
    -H "Authorization: Bearer 你的API_KEY"

OpenAI-compatible 客户端：
Base URL: http://127.0.0.1:8317/v1
API Key: config.yaml 里的 api-keys

如果通过 Nginx / 1Panel 反代，只反代 8317。不要给 /v1/* 加 Basic Auth。



sub2api
Wed, 13 May 2026 00:00:00 GMT
Github Repo
Sub2API Github Repo
说明
这是 sub2api + PostgreSQL + Redis 模板，附带可选的 sing-box 出站代理。
先创建 new-api 内网：
docker network create --driver bridge --internal newapi-sub2api

目录结构：
sub2api/
├── docker-compose.yml
├── .env
├── nginx/default.conf
├── sing-box/config.json
├── sub2api_data/
├── postgres_data/
└── redis_data/

不用 sing-box 时，删除 sing-box 服务、sub2api-proxy / sub2api-egress 网络、depends_on.sing-box 和 HTTP_PROXY / HTTPS_PROXY / ALL_PROXY / UPDATE_PROXY_URL。
docker-compose
services:
    sub2api:
        image: weishaw/sub2api:latest
        container_name: sub2api
        restart: unless-stopped
        ulimits:
            nofile:
                soft: 100000
                hard: 100000
        depends_on:
            postgres:
                condition: service_healthy
            redis:
                condition: service_healthy
            sing-box:
                condition: service_started
        volumes:
            - ./sub2api_data:/app/data
        environment:
            - AUTO_SETUP=true
            - SERVER_HOST=0.0.0.0
            - SERVER_PORT=8080
            - SERVER_MODE=${SERVER_MODE:-release}
            - RUN_MODE=${RUN_MODE:-standard}
            - TZ=${TZ:-Asia/Shanghai}

            - DATABASE_HOST=postgres
            - DATABASE_PORT=5432
            - DATABASE_USER=${POSTGRES_USER:-sub2api}
            - DATABASE_PASSWORD=${POSTGRES_PASSWORD:?POSTGRES_PASSWORD is required}
            - DATABASE_DBNAME=${POSTGRES_DB:-sub2api}
            - DATABASE_SSLMODE=disable
            - DATABASE_MAX_OPEN_CONNS=${DATABASE_MAX_OPEN_CONNS:-50}
            - DATABASE_MAX_IDLE_CONNS=${DATABASE_MAX_IDLE_CONNS:-10}
            - DATABASE_CONN_MAX_LIFETIME_MINUTES=${DATABASE_CONN_MAX_LIFETIME_MINUTES:-30}
            - DATABASE_CONN_MAX_IDLE_TIME_MINUTES=${DATABASE_CONN_MAX_IDLE_TIME_MINUTES:-5}

            - REDIS_HOST=redis
            - REDIS_PORT=6379
            - REDIS_PASSWORD=${REDIS_PASSWORD:?REDIS_PASSWORD is required}
            - REDIS_DB=${REDIS_DB:-0}
            - REDIS_POOL_SIZE=${REDIS_POOL_SIZE:-1024}
            - REDIS_MIN_IDLE_CONNS=${REDIS_MIN_IDLE_CONNS:-10}
            - REDIS_ENABLE_TLS=false

            - ADMIN_EMAIL=${ADMIN_EMAIL:-admin@example.com}
            - ADMIN_PASSWORD=${ADMIN_PASSWORD:?ADMIN_PASSWORD is required}
            - JWT_SECRET=${JWT_SECRET:?JWT_SECRET is required}
            - JWT_EXPIRE_HOUR=${JWT_EXPIRE_HOUR:-24}
            - TOTP_ENCRYPTION_KEY=${TOTP_ENCRYPTION_KEY:?TOTP_ENCRYPTION_KEY is required}

            # 可选：sub2api 出站走 sing-box
            - HTTP_PROXY=http://sing-box:7890
            - HTTPS_PROXY=http://sing-box:7890
            - ALL_PROXY=socks5h://sing-box:7890
            - UPDATE_PROXY_URL=http://sing-box:7890
            - NO_PROXY=localhost,127.0.0.1,::1,postgres,redis,sing-box,sub2api,new-api,newapi,*.local

            # 允许 new-api 通过 Docker 内网 HTTP 访问 sub2api
            - SECURITY_URL_ALLOWLIST_ENABLED=false
            - SECURITY_URL_ALLOWLIST_ALLOW_INSECURE_HTTP=true
            - SECURITY_URL_ALLOWLIST_ALLOW_PRIVATE_HOSTS=true
        networks:
            sub2api-internal:
                aliases:
                    - sub2api
            sub2api-proxy:
                aliases:
                    - sub2api
            newapi-sub2api:
                aliases:
                    - sub2api
        healthcheck:
            test: ["CMD", "wget", "-q", "-T", "5", "-O", "/dev/null", "http://localhost:8080/health"]
            interval: 30s
            timeout: 10s
            retries: 3
            start_period: 60s

    dashboard-proxy:
        image: nginx:1.27-alpine
        container_name: sub2api-dashboard-proxy
        restart: unless-stopped
        depends_on:
            sub2api:
                condition: service_started
        ports:
            - "127.0.0.1:38580:80"
        volumes:
            - ./nginx/default.conf:/etc/nginx/conf.d/default.conf:ro
        networks:
            sub2api-internal:
                aliases:
                    - sub2api-dashboard-proxy

    postgres:
        image: postgres:18-alpine
        container_name: sub2api-postgres
        restart: unless-stopped
        environment:
            - POSTGRES_USER=${POSTGRES_USER:-sub2api}
            - POSTGRES_PASSWORD=${POSTGRES_PASSWORD:?POSTGRES_PASSWORD is required}
            - POSTGRES_DB=${POSTGRES_DB:-sub2api}
            - PGDATA=/var/lib/postgresql/data
            - TZ=${TZ:-Asia/Shanghai}
        volumes:
            - ./postgres_data:/var/lib/postgresql/data
        networks:
            sub2api-internal:
                aliases:
                    - postgres
        healthcheck:
            test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-sub2api} -d ${POSTGRES_DB:-sub2api} -h 127.0.0.1"]
            interval: 10s
            timeout: 5s
            retries: 10
            start_period: 20s

    redis:
        image: redis:8-alpine
        container_name: sub2api-redis
        restart: unless-stopped
        command: >
            sh -c 'redis-server
            --requirepass "$$REDIS_PASSWORD"
            --save 60 1
            --appendonly yes
            --appendfsync everysec'
        volumes:
            - ./redis_data:/data
        environment:
            - TZ=${TZ:-Asia/Shanghai}
            - REDIS_PASSWORD=${REDIS_PASSWORD:?REDIS_PASSWORD is required}
            - REDISCLI_AUTH=${REDIS_PASSWORD:?REDIS_PASSWORD is required}
        networks:
            sub2api-internal:
                aliases:
                    - redis
        healthcheck:
            test: ["CMD-SHELL", "redis-cli -a \"$${REDIS_PASSWORD}\" ping | grep PONG"]
            interval: 10s
            timeout: 5s
            retries: 10
            start_period: 10s

    sing-box:
        image: ghcr.io/sagernet/sing-box:latest
        container_name: sub2api-sing-box
        restart: unless-stopped
        command: run -c /etc/sing-box/config.json -D /var/lib/sing-box
        volumes:
            - ./sing-box/config.json:/etc/sing-box/config.json:ro
            - ./sing-box-data:/var/lib/sing-box
        networks:
            sub2api-proxy:
                aliases:
                    - sing-box
            sub2api-egress:
        healthcheck:
            test: ["CMD", "sing-box", "check", "-c", "/etc/sing-box/config.json"]
            interval: 30s
            timeout: 10s
            retries: 3

networks:
    sub2api-internal:
        driver: bridge
        internal: true

    sub2api-proxy:
        driver: bridge
        internal: true

    sub2api-egress:
        driver: bridge

    newapi-sub2api:
        external: true

env
TZ=Asia/Shanghai

SERVER_MODE=release
RUN_MODE=standard

POSTGRES_USER=sub2api
POSTGRES_PASSWORD=换成你的PostgreSQL强密码
POSTGRES_DB=sub2api

REDIS_PASSWORD=换成你的Redis强密码
REDIS_DB=0

ADMIN_EMAIL=admin@example.com
ADMIN_PASSWORD=换成你的sub2api后台密码

JWT_SECRET=换成openssl生成的hex
TOTP_ENCRYPTION_KEY=换成openssl生成的hex

生成随机值：
openssl rand -hex 24
openssl rand -hex 24
openssl rand -hex 32
openssl rand -hex 32

nginx/default.conf
server {
    listen 80;

    location / {
        proxy_pass http://sub2api:8080;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

sing-box/config.json
可选。只在需要代理出站时创建：
{
  "log": {
    "level": "info",
    "timestamp": true
  },
  "inbounds": [
    {
      "type": "mixed",
      "tag": "mixed-in",
      "listen": "::",
      "listen_port": 7890
    }
  ],
  "outbounds": [
    {
      "type": "vless",
      "tag": "proxy",
      "server": "你的VLESS服务器IP或域名",
      "server_port": 443,
      "uuid": "你的完整UUID",
      "flow": "xtls-rprx-vision",
      "tls": {
        "enabled": true,
        "server_name": "你的Reality伪装域名",
        "utls": {
          "enabled": true,
          "fingerprint": "chrome"
        },
        "reality": {
          "enabled": true,
          "public_key": "你的Reality公钥",
          "short_id": "你的short_id"
        }
      },
      "packet_encoding": "xudp"
    },
    {
      "type": "direct",
      "tag": "direct"
    }
  ],
  "route": {
    "final": "proxy"
  }
}

mixed 同时提供 HTTP proxy 和 SOCKS proxy；不需要写旧版 sniff / dns-out。
启动
docker compose up -d
docker compose logs -f sub2api

WebUI：
http://127.0.0.1:38580

远程访问：
ssh -p 22 -L 38580:127.0.0.1:38580 user@你的服务器IP

new-api 上游地址：
http://sub2api:8080

验证
curl -v http://127.0.0.1:38580/health
docker compose ps

启用 sing-box 时：
docker compose run --rm sing-box check -c /etc/sing-box/config.json
docker exec -it sub2api sh
wget -O- https://ipinfo.io

重点备份：
.env
docker-compose.yml
nginx/default.conf
sub2api_data/
postgres_data/
redis_data/
sing-box/config.json

postgres_data/ 初始化后，再改 .env 的 POSTGRES_PASSWORD 不会自动修改数据库内部密码。新部署可以删数据重来，已有数据不要直接删目录。



AstrBot
Tue, 12 May 2026 00:00:00 GMT
AstrBot 使用指南
1. AstrBot 是什么
Github Repo
AstrBot 是开源的一体化 Agentic chatbot infrastructure。它的核心功能是把 Agent 接入 QQ、Telegram、飞书、钉钉、Slack、Discord、企业微信、微信公众号等 IM 平台，并在 WebUI 中统一管理模型、插件、知识库、MCP、Skills、人格设定、上下文压缩和沙盒执行。
官方文档：

https://astrbot.app/
https://docs.astrbot.app/
https://docs.astrbot.app/deploy/astrbot/docker.html
https://docs.astrbot.app/use/astrbot-agent-sandbox.html


截至 2026-05-12，官方 README 将 AstrBot 定位为面向个人、开发者和团队的 conversational AI infrastructure；最新 GitHub release 为 v4.24.2（2026-05-03）。v4.24.x 的重点包括 Plugin Pages、插件国际化、插件提供 Skills、WebUI 中编辑 Skills、CUA Computer Use 沙盒、后台 Shell、Provider 配置优化和若干安全修复。


2. 安装与更新
2.1 uv 一键部署
适合本地试用：
uv tool install astrbot --python 3.12
astrbot init
astrbot run

更新：
uv tool upgrade astrbot --python 3.12

注意：

AstrBot 要求 Python 3.12+
uv 部署不支持通过 WebUI 升级
macOS 首次运行可能因系统安全检查慢 10-20s

2.2 Docker
Docker Compose 部署：

AstrBot Docker Compose 1Panel版

该模板包含三部分：

AstrBot 主服务
NapCat / OneBot：用于接入 QQ 个人号，可选
Shipyard Neo：用于 Agent Sandbox，可选

官方文档：

Deploy AstrBot with Docker

仓库根目录当前也直接提供：

Dockerfile
compose.yml
compose-with-shipyard.yml

docker compose up -d
docker compose logs -f astrbot

官方镜像：
soulter/astrbot:latest

默认 WebUI 端口：
6185

2.3 其他部署方式
官方还提供桌面端、Launcher、AUR、宝塔、1Panel、CasaOS、RainYun、Replit、Kubernetes、手动源码部署。一般建议：

本地试用：uv
长期运行：Docker
桌面 ChatUI：AstrBot Desktop
面板用户：直接用 1Panel / 宝塔应用商店


3. 快速开始
最短路径：
uv tool install astrbot --python 3.12
astrbot init
astrbot run

Docker 路径：
docker compose up -d
docker compose logs -f astrbot

然后在 WebUI 中完成三件事：

配置模型服务
接入一个消息平台
按需安装插件、知识库、MCP、Skills 或沙盒

如果只启动了 AstrBot 但没有接入平台，它只是一个可管理的 Agent 后端，还不能在 IM 里回复消息。

4. 常用命令
astrbot init
astrbot run

Docker 管理：
docker compose up -d
docker compose down
docker compose logs -f astrbot
docker compose pull
docker compose up -d

进入容器：
docker exec -it astrbot bash

查看 WebUI：
http://127.0.0.1:6185

初始账号密码通常为：
astrbot / astrbot

首次登录后立刻修改密码。

5. 配置与数据目录
Docker 内数据目录：
/AstrBot/data

宿主机推荐挂载：
./data:/AstrBot/data

这里会保存：
config/       配置
plugins/      插件
data/         运行数据
temp/         临时文件
logs/         日志

规则：

定期备份 data/
不提交 API keys、平台 token、会话数据
不让多个 AstrBot 实例同时写同一个 data/
迁移服务器时，data/ 比 compose 文件更重要


6. 模型与中转
AstrBot 支持 OpenAI-compatible、Anthropic、Gemini、Moonshot、智谱、DeepSeek、Ollama、LM Studio、硅基流动、PPIO、ModelScope、OneAPI、Dify、百炼、Coze 等。
常见顺序：

在 WebUI 添加 Provider
填写 API Key / Base URL / 模型名
测试 Provider
设置默认模型

OpenAI-compatible endpoint 常见检查：
base_url = https://api.example.com/v1
model = provider暴露的真实模型名

Docker 访问宿主机 Ollama / LM Studio 时，优先使用：
http://host.docker.internal:11434
http://host.docker.internal:1234

Linux Docker 下还需要在 compose 里加入 host.docker.internal:host-gateway。同时确保宿主机模型服务监听 0.0.0.0，不是只监听 127.0.0.1。

7. 消息平台
官方 README 当前列出的官方平台包括：
QQ / OneBot v11 / Telegram / 企业微信 / Wecom AI Bot
微信公众号 / 飞书 / 钉钉 / Slack / Discord / LINE
Satori / KOOK / Misskey / Mattermost

社区平台包括：
Matrix / Rocket.Chat / VoceChat

流程基本一致：

在目标平台创建 bot / app
在 WebUI 添加平台适配器
填写 token、secret、回调地址或 websocket 配置
保存并重启 / 热加载
通过日志确认连接成功

飞书、钉钉、企业微信、Telegram 更适合正式机器人场景；QQ 个人号通常走 NapCat / OneBot v11。
7.1 NapCat / OneBot
NapCat 是常见的 QQ 个人号接入方案，通常通过 OneBot v11 WebSocket 和 AstrBot 通信。部署关系可以理解为：
QQ 个人号
    ↓
NapCat
    ↓ OneBot v11
AstrBot

1Panel / Docker 部署时，建议让 astrbot 和 napcat 放在同一个 Docker network 中，再在 AstrBot WebUI 添加 OneBot v11 适配器。常见端口：
6099  NapCat WebUI
6199  AstrBot OneBot v11 WebSocket

注意：

NapCat 需要独立保存 QQ 登录态和配置
不要把 NapCat WebUI 无保护暴露到公网
QQ 个人号方案有平台风控风险，生产业务更建议用官方机器人、企业微信、飞书、钉钉或 Telegram


8. 核心功能
8.1 WebUI / Web ChatUI
WebUI 用于管理 Provider、平台、插件、知识库、MCP、Skills、配置和日志；Web ChatUI 可以直接作为浏览器聊天入口，并集成 Agent Sandbox 和网页搜索。
8.2 插件
AstrBot 的插件生态很大，官方 README 当前写明有 1000+ 插件可一键安装。v4.24.x 后插件能力继续增强：

插件可以暴露 Dashboard 页面
插件支持国际化
插件可以提供 Skills
插件详情页、短描述、置顶和官方插件存储下载能力增强

旧教程里某些“内置命令默认存在”的说法可能已经过时；部分低频命令已经迁移到插件，例如 builtin_commands_extension。
8.3 Skills / MCP / 知识库
AstrBot 支持：

Skills：沉淀可复用能力和提示结构
MCP：接入外部工具服务器
知识库：上传文档后做检索增强
自动上下文压缩：长会话中降低上下文溢出概率

使用顺序建议先配模型和平台，再逐步加知识库、MCP 和 Skills。
8.4 Agent Sandbox
AstrBot 从 v4.12.0 起引入 Agent 沙盒，用于替代旧代码执行器。当前驱动包括：
Shipyard Neo   当前推荐
Shipyard       旧方案，兼容保留
CUA            Computer Use 运行时

Shipyard Neo 由 Bay、Ship、Gull 组成：

Bay：控制面 API
Ship：Python / Shell / 文件系统执行环境
Gull：浏览器能力

部署关系：
AstrBot
    ↓ Shipyard Neo API
Bay
    ↓ Docker socket
Ship / Gull sandbox containers

Shipyard Neo 的工作区根目录固定为 /workspace。在 AstrBot 的沙盒文件工具里应传相对路径，例如 reports/result.txt，不要传 /workspace/reports/result.txt。
WebUI 配置入口：
AI 配置 -> Agent Computer Use
Computer Use Runtime = sandbox
沙箱环境驱动器 = Shipyard Neo / CUA

如果使用本文配套 compose，Shipyard Neo 的典型配置是：
Shipyard Neo API Endpoint = http://astrbot-bay:8114
Shipyard Neo Access Token = Bay config.yaml 中的 security.api_key
Shipyard Neo Profile = python-default

资源建议：

仅 AstrBot：1C1G 可试用，长期建议 2C2G+
AstrBot + Shipyard Neo：至少 2C4G 并开启 Swap
启用浏览器 / CUA：更适合资源充足的独立机器或 homelab

低配 VPS 不建议把 AstrBot、浏览器沙盒和多个 IM 适配器全塞在一起。
8.5 主动任务 / Cron
AstrBot 支持主动型 Agent 能力和 Cron 任务，可用于定时摘要、提醒、巡检、消息推送等。生产使用时应限制可主动发送的会话范围，避免普通用户借工具向任意 session 发消息。

9. Docker 文件访问与安全
AstrBot 容器只能访问容器内路径和显式挂载目录。要让它处理宿主机文件，需要挂载：
volumes:
    - ./data:/AstrBot/data
    - /opt/projects:/workspace/projects

安全规则：

不挂载宿主机根目录
不把 secrets 目录交给 Agent
WebUI 不直接公网裸奔
首次登录后修改默认密码
只开放必要端口
沙盒服务不要匿名访问
使用 Shipyard Neo 时，security.api_key 必须是强随机字符串
Bay 需要 Docker socket，最好单独部署在更可信、更有资源的机器上


10. 排错
10.1 WebUI 打不开
确认容器运行：
docker compose logs -f astrbot

确认端口：
6185

如果通过 1Panel 反代，目标应是：
http://astrbot:6185

不要在 Docker 网络里把反代目标写成 127.0.0.1:6185。
10.2 平台收不到消息
检查：

平台 token / app secret 是否正确
webhook 地址是否公网可达
websocket 模式是否连上
平台事件订阅是否启用
AstrBot 日志里是否有适配器报错

10.3 模型不可用
检查：

Provider 是否启用
API Key 是否有效
Base URL 是否带 /v1
模型名是否真实存在
容器内是否能访问模型网关

10.4 沙盒不可用
检查：

WebUI 中 Computer Use Runtime 是否设为 sandbox
Shipyard Neo Endpoint 是否可访问
Bay API Key 是否一致
Docker socket 是否挂载给 Bay
config.yaml 中 network 是否和 compose 网络一致
宿主机资源是否足够


11. 参考链接
https://github.com/AstrBotDevs/AstrBot
https://github.com/AstrBotDevs/AstrBot/releases
https://astrbot.app/
https://docs.astrbot.app/
https://docs.astrbot.app/deploy/astrbot/docker.html
https://docs.astrbot.app/use/astrbot-agent-sandbox.html
https://github.com/AstrBotDevs/AstrBot-desktop
https://github.com/AstrBotDevs/builtin_commands_extension




astrbot
Tue, 12 May 2026 00:00:00 GMT
Github Repo
AstrBot Github Repo
docker-compose
networks:
    1panel-network:
        external: true

services:
    astrbot:
        container_name: astrbot
        image: ${ASTRBOT_IMAGE}
        restart: unless-stopped
        security_opt:
            - no-new-privileges:true
        env_file:
            - .env
        environment:
            - TZ=${TIME_ZONE}
        labels:
            createdBy: Apps
        networks:
            - 1panel-network
        extra_hosts:
            - "host.docker.internal:host-gateway"
        ports:
            - ${HOST_IP}:${ASTRBOT_WEBUI_HOST_PORT}:6185
            - ${HOST_IP}:${ASTRBOT_ONEBOT_HOST_PORT}:6199
            - ${HOST_IP}:${ASTRBOT_WECHAT_CALLBACK_HOST_PORT}:11451
        volumes:
            - ./data:/AstrBot/data
        healthcheck:
            test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:6185', timeout=5)"]
            interval: 30s
            timeout: 8s
            start_period: 40s
            retries: 5

env
TIME_ZONE=Asia/Shanghai
HOST_IP=127.0.0.1

ASTRBOT_IMAGE=soulter/astrbot:latest

# WebUI
ASTRBOT_WEBUI_HOST_PORT=6185

# OneBot v11 / NapCat WebSocket，可选
ASTRBOT_ONEBOT_HOST_PORT=6199

# 个人微信 / Gewechat callback，可选
ASTRBOT_WECHAT_CALLBACK_HOST_PORT=11451

如果接入微信公众号、企业微信或 QQ 官方 Webhook，再按需暴露对应回调端口。旧版常见端口是 6194、6195、6196，以 WebUI / 官方适配器文档中的实际配置为准。
启动：
docker compose up -d
docker compose logs -f astrbot

WebUI：
http://127.0.0.1:6185

初始账号密码通常是：
astrbot / astrbot

首次登录后立刻修改密码。
不要直接把 6185 暴露到公网，建议 HOST_IP=127.0.0.1 后再通过 1Panel 反代访问。
1Panel 反代目标：
http://astrbot:6185

如果需要让 AstrBot 访问更多宿主机目录，用 volumes 显式挂载：
volumes:
    - ./data:/AstrBot/data
    - /opt/projects:/workspace/projects

在 AstrBot 中使用容器内路径：
/workspace/projects

这只是 AstrBot 主容器能访问的路径。Shipyard Neo 沙盒的文件工具以 /workspace 为根目录，调用时应传相对路径。
NapCat / OneBot
QQ 个人号通常通过 NapCat / OneBot v11 接入。更推荐参考 NapCat 官方的 AstrBot compose；如果只是在同一个 1Panel 网络里连接，可以额外部署：
services:
    napcat:
        image: mlikiowa/napcat-docker:latest
        container_name: napcat
        restart: unless-stopped
        environment:
            - NAPCAT_UID=${NAPCAT_UID}
            - NAPCAT_GID=${NAPCAT_GID}
            - MODE=astrbot
        networks:
            - 1panel-network
        ports:
            - ${HOST_IP}:${NAPCAT_WEBUI_HOST_PORT}:6099
        volumes:
            - ./napcat/config:/app/napcat/config
            - ./ntqq:/app/.config/QQ

对应 .env：
NAPCAT_UID=1000
NAPCAT_GID=1000
NAPCAT_WEBUI_HOST_PORT=6099

AstrBot 侧按 WebUI 提示添加 OneBot v11 适配器。
Agent Sandbox
AstrBot 的沙盒执行能力建议使用 Shipyard Neo。低配 VPS 不建议默认开启；需要 Python / Shell / 浏览器 / Computer Use 时再部署。
官方推荐单独部署 Shipyard Neo：
git clone https://github.com/AstrBotDevs/shipyard-neo
cd shipyard-neo/deploy/docker
openssl rand -hex 32
# 修改 config.yaml 中 security.api_key 和 docker.network
docker compose up -d

如果要和 AstrBot 放在同一个 1Panel 网络中，核心配置是：
services:
    bay:
        image: ghcr.io/astrbotdevs/shipyard-neo-bay:latest
        container_name: astrbot-bay
        restart: unless-stopped
        environment:
            - BAY_CONFIG_FILE=/app/config.yaml
            - BAY_DATA_DIR=/app/data
        networks:
            - 1panel-network
        ports:
            - ${HOST_IP}:${BAY_HOST_PORT}:8114
        volumes:
            - /var/run/docker.sock:/var/run/docker.sock
            - ./shipyard/config.yaml:/app/config.yaml:ro
            - ./shipyard/data:/app/data
            - ./shipyard/cargos:/var/lib/bay/cargos
        healthcheck:
            test: ["CMD", "curl", "-f", "http://127.0.0.1:8114/health"]
            interval: 30s
            timeout: 10s
            start_period: 15s
            retries: 5

对应 .env：
BAY_HOST_PORT=8114

shipyard/config.yaml 最小关键项：
server:
  host: "0.0.0.0"
  port: 8114

database:
  url: "sqlite+aiosqlite:///./data/bay.db"
  echo: false

driver:
  type: docker
  image_pull_policy: always
  docker:
    socket: "unix:///var/run/docker.sock"
    connect_mode: container_network
    network: "1panel-network"
    publish_ports: false
    host_port: null

cargo:
  root_path: "/var/lib/bay/cargos"
  default_size_limit_mb: 1024
  mount_path: "/workspace"

security:
  api_key: "换成 openssl rand -hex 32 生成的强随机字符串"
  allow_anonymous: false

profiles:
  - id: python-default
    description: "Python / Shell / filesystem sandbox"
    image: "ghcr.io/astrbotdevs/shipyard-neo-ship:latest"
    runtime_type: ship
    runtime_port: 8123
    resources:
      cpus: 1.0
      memory: "1g"
    capabilities:
      - filesystem
      - shell
      - python
    idle_timeout: 1800
    warm_pool_size: 0
    env: {}

gc:
  enabled: true
  run_on_startup: true
  interval_seconds: 300
  instance_id: "bay-prod"
  idle_session:
    enabled: true
  expired_sandbox:
    enabled: true
  orphan_cargo:
    enabled: true
  orphan_container:
    enabled: true

AstrBot WebUI 中配置：
AI 配置 -> Agent Computer Use
Computer Use Runtime = sandbox
沙箱环境驱动器 = Shipyard Neo
Shipyard Neo API Endpoint = http://astrbot-bay:8114
Shipyard Neo Access Token = config.yaml 中的 security.api_key
Shipyard Neo Profile = python-default

如果需要浏览器能力，再增加 browser-python profile，并使用 ghcr.io/astrbotdevs/shipyard-neo-gull:latest。浏览器沙盒更吃资源，建议至少 2C4G 并开启 Swap。



Hermes Agent
Mon, 11 May 2026 00:00:00 GMT
Hermes Agent 使用指南
1. Hermes Agent 是什么
Github Repo
Hermes Agent（命令 hermes）是长期运行型 personal agent，独特优势在于长期记忆、skills自我改进，其余功能类似openclaw，跨会话检索、cron 定时任务，多入口支持如：Telegram、飞书等。
官方文档：

https://hermes-agent.nousresearch.com/
https://github.com/NousResearch/hermes-agent/blob/main/website/docs/user-guide/docker.md
https://github.com/NousResearch/hermes-agent/blob/main/docker-compose.yml


截至 2026-05-11，官方 README 仍称它为 “The agent that grows with you”。它不像 Claude Code / OpenCode 那样主要面向本地项目 TUI，更适合常驻 VPS，通过 gateway 接入多个聊天渠道；模型来源支持 OpenRouter、OpenAI、自定义 endpoint 等。v0.12.0 起官方强调 Autonomous Curator：后台周期性整理、评分、剪枝、合并 skill library，并改进“哪些经验值得保存”的自我更新循环。


2. 安装与更新
2.1 Linux / macOS / WSL2 / Termux
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
source ~/.bashrc

2.2 Windows
irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1 | iex

补充：

原生 Windows 安装目录通常为 %LOCALAPPDATA%\hermes
WSL2 安装目录通常为 ~/.hermes
原生 Windows 仍偏 early beta；dashboard chat pane 依赖 POSIX PTY，稳定使用建议放在 WSL2 内

2.3 Docker
Docker Compose部署：

Hermes Agent Docker Compose 1panel版

docker compose run --rm hermes setup
docker compose up -d

setup 会把 .env、config.yaml 等配置写入 /opt/data 对应的宿主机目录。
2.4 更新
脚本安装：重新执行安装脚本。Docker 部署：
docker compose pull
docker compose up -d


3. 快速开始
3.1 本地 CLI
hermes setup
hermes model
hermes tools
hermes

3.2 Gateway 服务
hermes gateway run

官方 Docker 端口：

8642：gateway API / health endpoint
9119：dashboard；浏览器 Chat tab 需要 HERMES_DASHBOARD_TUI=1

健康检查：
curl http://127.0.0.1:8642/health

域名反代：
dashboard: http://hermes-agent:9119
gateway:   http://hermes-agent:8642

4. 常用命令
hermes
hermes setup
hermes model
hermes tools
hermes config set
hermes gateway run
hermes update
hermes doctor

Docker 管理：
docker compose up -d
docker compose down
docker compose logs -f hermes
docker compose pull

容器内打开 Hermes CLI：
docker exec -it hermes-agent bash
/opt/hermes/.venv/bin/hermes

排查优先看日志：
docker compose logs -f hermes


5. 配置与数据目录
Docker 内数据目录：
/opt/data

常见内容：
.env          API keys and secrets
config.yaml   Hermes 配置
SOUL.md       Agent personality / identity
sessions/     会话历史
memories/     长期记忆
skills/       skills
cron/         定时任务
hooks/        事件 hooks
logs/         日志
skins/        CLI 皮肤

规则：

定期备份 data/
不提交 .env、API keys、sessions、memories
不让多个 gateway 同时写同一个 data 目录
迁移服务器时，data/ 比 compose 文件更重要


6. 模型与中转
常见环境变量：
OPENROUTER_API_KEY=
OPENAI_API_KEY=
ANTHROPIC_API_KEY=
GOOGLE_API_KEY=
GEMINI_API_KEY=
DEEPSEEK_API_KEY=

OpenAI-compatible endpoint（vLLM / LiteLLM / xinference）检查：

base_url 形如 http://vllm:8000/v1，不要带结尾斜杠
Hermes 容器内能访问模型服务
模型服务监听 0.0.0.0，不是只监听 127.0.0.1

docker exec hermes-agent curl -s http://vllm:8000/v1/models


7. 聊天渠道
Gateway 启动后，CLI 和聊天平台共享很多 slash command：
/new
/reset
/model
/personality
/retry
/undo
/compress
/usage
/skills
/stop

Telegram 最小配置：
TELEGRAM_BOT_TOKEN=你的bot token
TELEGRAM_ALLOWED_USERS=你的telegram user id

流程：

BotFather 创建 bot。
.env 写入 token 和 allowed users。
setup / 配置流程启用 Telegram channel。
重启并看日志。

docker compose restart hermes
docker compose logs -f hermes

先只允许自己的 Telegram user id，不要一开始放开群聊。
7.1 飞书 / Lark
官方 Feishu/Lark 适配支持私聊、群聊、cron 结果投递、文本、图片、音频、文件附件。推荐 websocket 模式：Hermes 主动连飞书，不需要公网 webhook。
最短流程：
hermes gateway setup

选择 Feishu / Lark 后扫码创建，或手动填写 App ID / App Secret。
手动 .env 最小项：
FEISHU_APP_ID=cli_xxx
FEISHU_APP_SECRET=secret_xxx
FEISHU_DOMAIN=feishu
FEISHU_CONNECTION_MODE=websocket
FEISHU_ALLOWED_USERS=ou_xxx,ou_yyy
FEISHU_HOME_CHANNEL=oc_xxx

说明：

FEISHU_DOMAIN=feishu 用国内飞书，lark 用国际版
私聊默认每条消息都响应
群聊默认需要 @bot
FEISHU_HOME_CHANNEL 接收 cron 结果和跨平台通知
生产环境务必设置 FEISHU_ALLOWED_USERS


8. 核心功能
8.1 Tools
hermes tools

配置启用哪些工具。官方 README 提到 Hermes 有 toolset system 和 40+ tools；按场景逐步开启，不建议一开始全放开。
8.2 Skills
Hermes 会在使用中创建和改进 skills，也兼容 agentskills.io 开放标准。常用入口：
/skills
/

自我更新的关键在 skills：Hermes 会把可复用流程沉淀为 procedural memory；Autonomous Curator 按 gateway 的 cron ticker 后台运行，默认 7 天周期，负责合并重复技能、剪掉低价值技能、保留高价值经验。
8.3 Memory
长期记忆、用户画像和跨会话信息主要在：
data/memories/
data/sessions/

8.4 Cron
内置 cron scheduler，可把日报、备份、审计、项目跟踪等任务投递到配置好的聊天平台。数据目录：
cron/


9. Docker 文件访问与安全
Hermes 容器只能访问容器内文件和显式挂载目录。要管理宿主机项目，在 compose 里加 volumes：
volumes:
    - ./data:/opt/data
    - /opt/projects:/workspace/projects

在 Hermes 中使用容器内路径：
/workspace/projects

安全规则：

不挂载宿主机根目录
只挂载需要管理的目录
secrets 目录不要默认交给 agent
dashboard 域名加访问密码或 IP 白名单
API_SERVER_KEY 使用强随机字符串
不直接暴露 9119 / 8642
不覆盖官方镜像 entrypoint；官方要求保留 /opt/hermes/docker/entrypoint.sh，否则可能生成 root-owned 状态文件

10. 排错
10.1 dashboard 访问不了
确认：
HERMES_DASHBOARD=1
HERMES_DASHBOARD_HOST=0.0.0.0
HERMES_DASHBOARD_PORT=9119

Chat tab 不可用再确认：
HERMES_DASHBOARD_TUI=1

10.2 API 无法访问
确认：
API_SERVER_ENABLED=true
API_SERVER_HOST=0.0.0.0
API_SERVER_KEY=至少8位强随机字符串

测试：
curl http://127.0.0.1:8642/health

10.3 data 权限问题
查宿主机用户：
id -u
id -g

然后修改：
HERMES_UID=
HERMES_GID=

官方 Docker 文档说明容器入口会切换到非 root 的 hermes 用户，默认 UID 为 10000。挂载目录不可写时，通常就是这里不匹配。
10.4 浏览器工具异常
如果 Playwright / 浏览器工具异常，给容器加：
shm_size: 1g




OpenClaw
Mon, 11 May 2026 00:00:00 GMT
OpenClaw 使用指南
1. OpenClaw 是什么
Github Repo
OpenClaw（命令 openclaw）是 self-hosted personal AI assistant：一个常驻 Gateway 连接 WhatsApp、Telegram、Slack、Discord、飞书 / Lark、Signal、iMessage、Matrix、Teams、WebChat 等渠道，再把消息交给 agent、tools、skills、memory、cron 处理。
官方文档：

https://docs.openclaw.ai
https://docs.openclaw.ai/start/getting-started
https://docs.openclaw.ai/install/docker
https://docs.openclaw.ai/channels/feishu


截至 2026-05-11，官方 README 仍把 OpenClaw 定位为 Personal AI Assistant，并强调 Gateway 只是 control plane，产品本体是 assistant。当前推荐运行时是 Node 24，最低 Node 22.16+；Windows 建议通过 WSL2 使用。最新 GitHub release 已到 v2026.5.6（2026-05-06），旧文中的 v2026.4.12 已过时。

1.1 推荐配置
>= 2 核 2G（建议开 SWAP），最好 >= 2 核 4G。
若服务器性能不足，可考虑基于 Rust 的轻量替代方案 zeroclaw。
2. 安装与更新
2.1 npm / pnpm
npm install -g openclaw@latest
# 或
pnpm add -g openclaw@latest

初始化：
openclaw onboard --install-daemon

onboard 会引导你配置 Gateway、模型、工作区、聊天渠道、skills 和后台服务。
2.2 onboard 关键选择
openclaw onboard 默认 quickstart：本地 Gateway、默认工作区、端口 18789、Token 认证、Tailscale 关闭。单机自用直接选默认；要远程访问、多设备、公开渠道，再走 advanced。
已有配置时：

Keep：保留现有配置，只补缺项
Modify：保留为主，逐步修改关键项
Reset：重置配置；优先 Config only，不要一开始 full reset

非交互模式必须显式承认风险：
openclaw onboard --non-interactive --accept-risk \
  --mode local \
  --gateway-bind loopback \
  --gateway-port 18789 \
  --install-daemon \
  --daemon-runtime node

2.3 Docker
Docker Compose部署：

OpenClaw Docker Compose 1panel版

官方 Docker 流程推荐从仓库根目录执行：
export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"
./scripts/docker/setup.sh

这个脚本会自动 onboarding、生成 Gateway token、写入 .env 并启动 compose。手写 compose 时，也要先跑一次 onboarding / config 写入，否则 Gateway 可能因为缺少 gateway.mode=local 拒绝启动。
2.4 更新
openclaw update
openclaw doctor

Docker 部署：
docker compose pull
docker compose up -d
docker compose run --rm openclaw-cli doctor


3. 快速开始
本地最短路径：
openclaw onboard --install-daemon
openclaw agent --message "Ship checklist" --thinking high
openclaw status --deep

前台启动 Gateway：
openclaw gateway run

默认端口：

18789：Gateway WebSocket、Control UI / WebChat、health endpoint
18790：bridge port，官方 compose 默认也暴露

浏览器打开：
http://127.0.0.1:18789/

Docker 健康检查：
curl http://127.0.0.1:18789/healthz
curl http://127.0.0.1:18789/readyz


4. 常用命令
openclaw onboard --install-daemon
openclaw configure
openclaw config get
openclaw agent --message "..."
openclaw gateway run
openclaw gateway restart
openclaw status --deep
openclaw logs --follow
openclaw doctor
openclaw health
openclaw gateway status
openclaw gateway probe

Docker 管理：
docker compose up -d
docker compose down
docker compose logs -f openclaw-gateway
docker compose run --rm openclaw-cli dashboard --no-open

渠道命令：
docker compose run --rm openclaw-cli channels login
docker compose run --rm openclaw-cli channels add
docker compose run --rm openclaw-cli channels add --channel telegram --token ""


5. 配置与数据目录
默认配置：
~/.openclaw/openclaw.json
~/.openclaw/.env
~/.openclaw/workspace/

openclaw.json 是 JSON5：支持注释和尾逗号，但 schema 校验严格。未知键、类型错误、非法值都会让 Gateway 拒绝启动。
Docker 内路径：
/home/node/.openclaw
/home/node/.openclaw/workspace

常见内容：
openclaw.json                 Gateway / agents / channels 配置
.env                          Gateway token 与模型服务 key
agents/*/agent/auth-profiles   provider OAuth / API-key auth
workspace/MEMORY.md            主记忆
workspace/memory/*.md          结构化记忆
workspace/sessions/            会话数据
workspace/cron/                定时任务运行记录

规则：

定期备份 .openclaw/ 或 Docker 的 config/、workspace/
不提交 .env、auth profiles、sessions、memory
Docker 中不要把宿主机路径写进容器运行时的 OPENCLAW_CONFIG_DIR
多 agent 用 openclaw agents add work，不要手动复制工作区混用

改配置的三种入口：
openclaw configure
openclaw configure --section models --section channels
openclaw config get
openclaw config set gateway.mode local

远程 / UI 场景可用 Gateway RPC：
openclaw gateway call config.get --params '{}'
openclaw gateway call config.patch --params '{"raw":"{ gateway: { mode: \"local\" } }","baseHash":""}'

如果通过 systemd / launchd 常驻运行，模型 Key 要同时对服务进程可见。Linux user service 常见做法是把 key 放进环境文件，再重启 Gateway；CLI 侧也可放入 ~/.openclaw/.env。

6. 模型与中转
常见认证方式：

OpenAI / Codex OAuth
OpenAI API key
Anthropic API key
OpenRouter API key
自定义 OpenAI-compatible / Anthropic-compatible endpoint

第三方 OpenAI-compatible 示例：
{
  models: {
    providers: {
      moonshot: {
        baseUrl: "https://api.moonshot.ai/v1",
        auth: "api-key",
        apiKey: "${MOONSHOT_API_KEY}",
        api: "openai-responses",
        models: [
          { id: "kimi-k2.5", name: "Kimi K2.5" }
        ]
      }
    }
  },
  agents: {
    defaults: {
      model: {
        primary: "moonshot/kimi-k2.5",
        fallbacks: [
          "anthropic/claude-sonnet-4-5",
          "openai/gpt-5.2"
        ]
      }
    }
  }
}

Docker 里访问宿主机 Ollama / LM Studio：
http://host.docker.internal:11434
http://host.docker.internal:1234

宿主机模型服务要监听 0.0.0.0，不是只监听 127.0.0.1。

7. 聊天渠道
官方 README 列出的渠道包括 WhatsApp、Telegram、Slack、Discord、Google Chat、Signal、iMessage、IRC、Teams、Matrix、飞书 / Lark、LINE、Mattermost、Nextcloud Talk、Nostr、Synology Chat、Twitch、Zalo、WeChat、QQ、WebChat 等。
安全默认：

私信默认 pairing：陌生人先收到配对码，批准后才处理消息
群聊默认建议 require mention
不要把 dmPolicy 改成 open 后再放开 "*"，除非你非常明确风险

批准配对：
openclaw pairing approve  

7.1 WhatsApp / Telegram
WhatsApp 扫码：
openclaw channels login

Telegram：
openclaw channels add --channel telegram --token ""
openclaw gateway restart

7.2 飞书 / Lark
官方 Feishu/Lark 渠道默认事件传输是 websocket，webhook 为可选模式。WebSocket 长连接不需要公网回调 URL，更适合个人服务器。
最短流程：
openclaw channels add
openclaw gateway restart

选择 Feishu 后填入 App ID / App Secret。飞书开放平台需要启用 Bot 能力、导入权限、事件订阅选择长连接，并添加 im.message.receive_v1。
手动配置结构：
{
  channels: {
    feishu: {
      enabled: true,
      domain: "feishu",
      dmPolicy: "pairing",
      groupPolicy: "allowlist",
      groupAllowFrom: ["oc_xxx"],
      requireMention: true,
      accounts: {
        main: {
          appId: "cli_xxx",
          appSecret: "${FEISHU_APP_SECRET}",
          name: "My AI assistant"
        }
      }
    }
  }
}

说明：

domain: "feishu" 用国内飞书，"lark" 用国际版
group ID 通常形如 oc_xxx
私聊默认 pairing；allowlist 模式下用 open_id，通常形如 ou_xxx
支持文本、图片、文件、音频、视频 / media、交互卡片


8. 核心功能
8.1 Gateway
Gateway 是 OpenClaw 的常驻控制平面，负责 channels、nodes、sessions、hooks、tools 和 WebChat。默认要求配置中存在：
{
  gateway: {
    mode: "local"
  }
}

如果缺少该项，Gateway 会拒绝启动；临时调试可用 --allow-unconfigured，但不要把它当成生产配置。
绑定与认证：

loopback：只允许本机访问，适合 SSH 隧道
tailnet：通过 Tailscale 访问，优先于直接开 LAN
lan：局域网访问，必须配 token / 反代认证 / 防火墙
非 loopback 绑定不要关闭认证

服务管理：
openclaw gateway install
openclaw gateway start
openclaw gateway restart
openclaw gateway stop
openclaw gateway uninstall

Tailscale：
{
  gateway: {
    tailscale: {
      mode: "serve"
    }
  }
}

serve 只暴露到 tailnet；funnel 是公网入口，默认不建议。
8.2 Memory
OpenClaw 的记忆不是黑盒数据库，而是工作区内可编辑的 Markdown：
MEMORY.md
memory/**/*.md

常用命令：
openclaw memory status
openclaw memory status --deep
openclaw memory index --verbose
openclaw memory search "release checklist"

关键行为：

默认会索引 MEMORY.md、memory/**/*.md
可用 memorySearch.extraPaths 加入额外路径
memory_search 返回片段、路径、行号和分数；完整上下文再用 memory_get
direct chat 默认展示引用；group / channel 默认可能不展示 source 行号
OAuth 不等于 embedding key；记忆检索需要单独可用的 embedding provider

provider 自动选择逻辑：先看本地模型，再看 OpenAI key，再看 Gemini key；都不可用则 memory search disabled。
OpenAI-compatible embedding 示例：
{
  agents: {
    defaults: {
      memorySearch: {
        provider: "openai",
        model: "text-embedding-3-small",
        remote: {
          baseUrl: "https://api.example.com/v1/",
          apiKey: "${OPENAI_COMPAT_API_KEY}"
        },
        sync: {
          watch: true
        }
      }
    }
  }
}

本地 embedding 示例：
{
  agents: {
    defaults: {
      memorySearch: {
        provider: "local",
        fallback: "none",
        local: {
          modelPath: "hf:ggml-org/embeddinggemma-300M-GGUF/embeddinggemma-300M-Q8_0.gguf"
        }
      }
    }
  }
}

8.3 Multi-Agent
多身份、多工作区、多渠道路由时，核心是：

agents.defaults：默认 agent 设置
agents.list[]：多个 agent，每个可有独立 workspace、model、tools、sandbox
bindings：把不同渠道、账号、会话路由到不同 agent

新增隔离 agent：
openclaw agents add work

新 agent 会有独立工作区、会话和认证配置；不要把多个身份直接混在一个 workspace。
8.4 Skills / Tools
OpenClaw 支持 bundled / managed / workspace skills。工具权限用 profile、allow、deny 控制：
{
  agents: {
    defaults: {
      tools: {
        profile: "messaging",
        deny: ["browser", "canvas"]
      }
    }
  }
}

暴露到群聊或多人渠道时，不要使用无边界的 full profile。
补充规则：

allow / deny 是显式白名单 / 黑名单
alsoAllow 用于在 profile 基础上增量放行
同一作用域不要同时写 allow 和 alsoAllow
whatsapp_login、cron、gateway 等高危工具通常应只允许 owner 使用
开自动化前建议启用 tools.loopDetection，避免重复工具调用无进展

高危执行权限建议按触发者收紧：
{
  agents: {
    defaults: {
      tools: {
        elevated: {
          enabled: true,
          allowFrom: {
            telegram: ["123456789"]
          }
        }
      }
    }
  }
}

8.5 Sandbox
OpenClaw 支持把工具执行放进 Docker sandbox。Gateway 仍在主机 / 主容器，工具执行在隔离容器，适合开启执行类工具时降低影响面。
{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",
        docker: {
          image: "openclaw-sandbox:bookworm-slim",
          network: "none",
          user: "1000:1000"
        }
      }
    }
  }
}

常用命令：
openclaw sandbox explain
openclaw sandbox list
openclaw sandbox recreate --all

安全护栏：

Docker sandbox 禁止 network: "host"
禁止 seccompProfile: "unconfined" 和 apparmorProfile: "unconfined"
binds.source 必须是绝对路径
镜像或 sandbox 配置更新后，建议 sandbox recreate --all

8.6 Cron / Hooks
Cron 适合日报、提醒、巡检、项目跟踪：
openclaw cron --help

常见行为：

cron add 默认可用 --announce 投递摘要
--no-deliver 只内部运行，不投递消息
一次性 --at 任务成功后默认删除；需要保留用 --keep-after-run

Hooks 适合事件驱动自动化：
openclaw hooks list --verbose
openclaw hooks enable session-memory

内置 hooks 可直接 enable / disable；插件 hooks 通常显示为 plugin:，由插件启停控制。
8.7 远程访问
远程访问优先顺序：

Tailscale serve
SSH 隧道
带认证的反向代理

SSH 隧道示例：
Host openclaw-vps
    HostName 
    User 
    LocalForward 18789 127.0.0.1:18789

ssh -N openclaw-vps

本机客户端连接 ws://127.0.0.1:18789，并提供同一个 OPENCLAW_GATEWAY_TOKEN。

9. Docker 文件访问与安全
OpenClaw Docker 容器只能访问容器内文件和显式挂载目录。要让 agent 管理宿主机项目，在 compose 中额外挂载：
volumes:
    - ./config:/home/node/.openclaw
    - ./workspace:/home/node/.openclaw/workspace
    - /opt/projects:/workspace/projects

安全规则：

Gateway 优先绑定 127.0.0.1 或只通过 1Panel / Nginx 反代访问
OPENCLAW_GATEWAY_TOKEN 使用强随机字符串
不直接公网暴露 18789
不挂载宿主机根目录
secrets 目录不要默认交给 agent
群聊和陌生私信保持 pairing / allowlist
非 main 会话建议启用 sandbox：agents.defaults.sandbox.mode: "non-main"
Docker 默认用户是 node，uid 通常为 1000；权限错误时优先修正挂载目录所有权


10. 排错
10.1 Gateway 起不来
确认配置里有：
{
  gateway: {
    mode: "local",
    bind: "lan"
  }
}

Docker 里修复：
docker compose run --rm openclaw-cli config set --batch-json '[{"path":"gateway.mode","value":"local"},{"path":"gateway.bind","value":"lan"}]'
docker compose up -d

10.2 Control UI 访问不了
确认容器健康：
docker compose logs -f openclaw-gateway
curl http://127.0.0.1:18789/healthz

如果需要重新拿 dashboard URL：
docker compose run --rm openclaw-cli dashboard --no-open

10.3 记忆检索不可用
openclaw memory status --deep

OAuth 不一定覆盖 embedding；按 memorySearch.provider 配齐 OpenAI / Gemini / local / voyage / mistral 等 embedding provider。
10.4 Docker 权限问题
官方镜像默认用 uid 1000：
sudo chown -R 1000:1000 ./config ./workspace

10.5 飞书消息不响应
确认：
openclaw --version
openclaw gateway status
openclaw logs --follow

再检查 dmPolicy、allowFrom、groupPolicy、groupAllowFrom、requireMention。群聊默认不要取消 mention 门控。



只说一句话
Mon, 11 May 2026 00:00:00 GMT
只说一句话

学习
1
生成10个问题，能区分出真正理解这个领域的人和只是背了知识点的人

生成十问，以辨真知于此领域者，抑或仅诵知识点者

Generate 10 questions that will differentiate between someone who really understands the field and someone who has just memorized the knowledge

2
我每答错一个问题就告知为什么错了，遗漏了什么

每错一问便告吾其故，有何所失。

For every question I got wrong, I was told why I got it wrong and what I missed.

润色
1
精简那些啰嗦重复、没有蕴含任何多余信息的废话，请始终保持语言的精炼，但是不能降低信息熵

简去赘辞复语，去除无益之言，务使辞约而意赅，然信息之丰，不可损也。

Streamline the verbose and repetitive nonsense that doesn't contain any extra information, and please always keep the language concise, but not reduce the information entropy

2
全文通查一遍，减少一些AI味，但是不能降低信息熵

通览全文，稍減机巧之气，然信息之丰，不可损也。

Checking through the whole text once reduces some of the AI flavor, but does not reduce the information entropy

3
为了避免出现错写漏写，你每次添加引理、定理、定义之前都必须阅读原始文献，使之较原始文献一字不差

欲免误书漏录，凡增引理、定理、定义之前，必先读原文，务使与原文毫厘不差。

In order to avoid misspellings and omissions, you must read the original literature every time before you add a quotation, theorem, or definition so that it is word-for-word better than the original literature

审查
1
以完美主义者的视角来为我的当前项目找茬

以完美主义者之观，审吾当前之业。

A perfectionist's perspective on finding fault with my current project

2
基于第一性原理来审查我的当前项目

以第一性原理审吾当前之业

Reviewing my current project based on first principles

清理
1
你只做检查和规划，告诉我需要删除的多余文件，我来亲自删除

惟卿但行稽查规划，告我当刪之冗余文件，余将亲刪之。

You just do the checking and planning, tell me the extra files that need to be removed, and I'll remove them myself

循环屎山构建流
1
必须要先完整拟定好一份最终plan,然后可以任意组合循环发出。
Do not deviate from my plan and follow your advice to carry out the next step

review

fix bugs you found




工程宪法
Mon, 11 May 2026 00:00:00 GMT
工程宪法

0. 适用前提
0.1 前提集合
本宪法建立在以下前提同时成立的条件下：

管理员 / USER 具备足够高的系统判断质量
骨架级分析报告具备足够高的事实质量、推理质量与利弊分析质量
骨架级决策以成熟分析为前提，而不以情绪、惯性或短期便利为依据

0.2 适用目标
本宪法的目标不是弥补低质量判断，而是在高质量判断成立的前提下，约束工程实现对该判断的忠实执行，从而避免以下结果：

系统背离本体
骨架被局部功能污染
结构性失稳在实现阶段累积
既有高质量判断在工程演化中被逐步削弱


1. 总体约束
1.1 总纲
系统设计满足以下总约束：

必须先定义总骨架与边界，再定义模块，再定义实现。
任何局部功能只能填入既定骨架，不得反向塑造骨架。
系统优先保持整体结构长期稳定，而不优先追求局部极致最优。
系统允许模块替换与实现迭代，但不允许日常功能迭代以侵蚀方式改写主骨架。

1.2 固定顺序
任一设计任务必须严格按以下顺序执行：

定义总骨架与边界
列出模块清单
细化实现逻辑

禁止跳过前项直接进入后项。
1.3 骨架约束
系统演进时必须满足：

骨架不因日常功能迭代而重构
模块可替换
实现可迭代
接口尽量稳定
状态模型尽量稳定
数据模型慎改
配置模型早定

1.4 优先级排序
当多个目标发生冲突时，系统必须按如下严格优先级排序作取舍：
正确性 / 功能实现

可用性 / 使用体验

根基兼容性

可维护性 / 可诊断性

性能

内存占用

外存占用

其它次级因素（如组件复用、工程复杂度控制等）

低优先级目标不得破坏高优先级目标。
1.5 根基兼容性在优先级中的定义
“根基兼容性”仅指对系统底层、长期稳定且被广泛接受的外部根基生态的兼容能力，以及对若干可能在一至两年内变化的根基外部参数的适应能力，例如：

CA 证书体系
系统网络协议
时区配置
Git 生态
编程语言生态及其长期约定

1.6 示例：RSS 阅读器
对一个纯人类阅读向 RSS 阅读器，即使首版只实现“添加订阅源并阅读文章”，在进入页面与功能实现前，仍必须先确定：

订阅源模型
文章模型
阅读状态模型
呈现层与抓取 / 存储的解耦关系
同步与导入导出的骨架挂接方式

否则后续“分类、收藏、OPML、全文缓存、云同步”等能力将倾向于以局部补丁方式侵入系统。

2. 元约束
2.1 完美主义约束
系统设计必须以完美主义作为持续自我审查标准，但不得以追求绝对完美为理由：

破坏骨架稳定
延迟必要落地
引入无上限复杂化

2.2 完美主义的作用
完美主义在本宪法中的作用不是驱动系统无限膨胀，而是持续检验以下条件是否仍成立：

边界是否干净
抽象是否稳定
实现是否统一
替换点是否明确
失败路径是否完整
当前方案是否忠于系统本体

2.3 结论
完美主义在工程中的合法形式是：

严格约束
持续审查
持续收敛

而不是：

失控扩张
过度设计
无限推迟实现


3. 骨架构造约束
3.1 根基兼容性原则
对于已经形成长期稳定生态、并在系统底层被反复验证数十年的标准、协议、接口习惯、工程范式与工具生态，系统应优先兼容与接入，而不是重复造轮子。
3.2 根基对象的判定条件
一个外部生态仅当同时满足以下多数条件时，才应被视为“根基对象”：

长期存在
底层基础
大规模接受
稳定运转
工程上具有历史沉淀

3.3 兼容与内生化规则

对根基对象：优先兼容，不轻易重造
对尚未形成长期生态、实现简单、替代成本低的能力：优先内嵌、重构或借鉴后纳入自身系统，不依赖外部兼容

3.4 值得兼容对象的判定条件
下列特征越多，越应兼容：

长期稳定
基础性强
行业共识强
自建收益低
自建维护成本高
脱离它会损失通用性与生存能力

3.5 不值得兼容对象的判定条件
下列特征越多，越不应兼容：

仍在快速变化
实现简单
没有形成深度行业共识
未来失效概率高
接入收益小于绑定风险

3.6 工程实现约束
所有外部环境依赖必须通过兼容层或适配层进入系统。

核心逻辑不得直接绑定环境细节。

3.7 简洁、有力、整洁、统一原则
系统骨架只围绕其本体所必需的核心对象、核心关系与高概率能力轴建立。

首版可以只实现其中一部分，但骨架不得被首版功能误导，也不得为异质能力提前膨胀。
3.8 本体优先规则
系统定义应围绕本体对象、核心关系和能力轴，而不是围绕首个实现版本的功能清单。

首版功能仅决定实现顺序，不定义系统本体。
3.9 抽象规则
抽象只能建立在长期稳定的本体对象、关系与能力边界上，不得建立在以下对象上：

首版实现
具体格式
局部技术细节

3.10 平级实现规则
属于同一变化族的具体实现，必须位于同一抽象之下，并以平级模块形式存在。

新增支持应优先表现为新增模块，而不是侵入既有主流程。
3.11 替代规则
系统优先支持模块替代，而不是流程改写。

实现应当可换，主干不应持续长出局部特判。
3.12 插件规则
插件机制不是架构起点，而是平级实现数量与替换需求增长后的自然承载形式。
3.13 能力纳入主骨架的三层判定
某能力进入主骨架，当且仅当其同时满足以下判定逻辑：

本体必要性判定：该能力直接服务于系统核心存在目的，或与之高度相关
同域延伸性判定：该能力属于同一问题域内自然延伸
异质侵入性判定：该能力不会引入一整套新的系统本体、依赖模型与复杂性，从而改变系统性质

若第三项不成立，则该能力不得进入主骨架。
3.14 统一性规则
系统允许复杂，但复杂必须以统一形式出现。

统一性至少体现在：

相同职责使用相同层级表达
相同错误使用相同错误模型表达
相同输入输出使用相同数据模型表达
相同配置项使用相同命名规范表达
相同模块使用相同目录结构表达
相同异步任务使用相同调度接口表达

3.15 示例：RSS 阅读器
对纯人类阅读向 RSS 阅读器，其本体对象不是“RSS 拉取页面”或“首版文章展示功能”，而是：

订阅源
文章
阅读过程
阅读状态
内容来源
内容解析
内容呈现
内容组织

因此，“多订阅分组、分类、书签、检索、全文缓存、云同步”属于同域延伸；“AI 分析、AI 问答、TTS、社交分享”若改变系统性质，则不应纳入主骨架。

4. 工程蓝图约束
4.1 蓝图要求
任何架构输出都必须向下细化到实现逻辑，不允许停留在概念层。
4.2 最低完备项
一个可施工的工程蓝图至少必须明确以下内容：

模块职责
调用关系
输入输出
状态变化
错误处理
配置入口
生命周期
扩展点
替换点
性能关键路径

4.3 判定规则
若一个方案只能说明系统大致分层、模块大致存在、目标大致正确，而不能继续下钻到具体调用逻辑与运行过程，则该方案只构成概念草图，不构成工程蓝图。
4.4 一致性要求
高层骨架、模块边界与实现逻辑之间必须连续。

不允许出现：

上层抽象与下层实现脱节
实现阶段临时发明破坏骨架的新结构

4.5 示例：RSS 阅读器
对“刷新订阅源”这一流程，工程蓝图必须能回答：

输入是什么
输出是什么
订阅源状态如何变化
新增文章数如何计算
网络失败、源格式异常、存储失败如何传播
抓取间隔、重试次数、超时时间如何进入配置
解析器、网络层、存储层分别从哪里替换
性能关键路径位于何处


5. 默认分层模型
5.1 四层架构 + 对象层
系统推荐采用“四层架构 + 对象层”的组织方式，并坚持壳核分离。
5.2 第一层：交互壳层
职责集合：

CLI / GUI / Web 界面
动画、样式、按钮、输入控件
平台适配
用户动作捕获
标准指令转译

唯一职责：
转译 + 呈现
5.3 第二层：指令接口层
职责集合：

接收标准化指令
校验合法性
识别状态变化
决定需要调用的能力
组织返回给交互层的结果结构

其映射关系定义为：

action → intent
intent → state delta
state delta → capability requests

5.4 第三层：流程协调层
职责集合：

任务拆分
调用顺序规划
前后依赖协调
状态推进
错误回滚或异常中止
后方任务分发

第三层不直接接触第五层对象。
5.5 第四层：能力执行层
职责集合：

数据计算
存储
读取
网络通信
文件系统操作
外部系统调用
后台处理
具体算法执行

5.6 第五层：对象层
对象层不属于骨架分层本身，但必须明确。

其作用是定义系统中实际操作的最小数据元对象。
典型对象形式包括：

.md
.pdf
.jpg
text::line
text::byte
sql::article
sql::feed
data::html
data::xml
data::opml

5.7 表现变化与业务变化分离规则
界面变化不天然等于业务状态变化。

只有在进入内部指令系统后，系统才判断哪些变化属于业务变化，哪些仅属于表现层变化。
5.8 示例：RSS 阅读器
当用户点击“打开某篇文章”时：

第一层只表达“打开文章”
第二层判断这是否涉及文章切换、已读状态更新、正文请求等状态变化
第三层组织具体流程
第四层执行读取、解析、状态写入
第五层明确所处理的对象是 sql::article、sql::reading_state、data::html 等


6. 一致性约束
6.1 边界封闭原则
一旦骨架划分完成，各层与各模块必须严格遵守职责边界。

任何新增功能都只能通过既定边界接入，不允许跨层直连、跨模块写入或绕过统一入口。
6.2 单一真相源原则
对任何核心对象、核心状态与核心配置，系统必须明确唯一可信来源。

同一事实不得在多个模块、多个缓存层、多个界面状态中并列作为最终依据。
6.3 示例：RSS 阅读器
文章“已读 / 未读”状态只能由统一的阅读状态模型作为真相源。

界面组件可以缓存显示结果，但不得与数据库状态并列为最终依据。

7. 运行可靠性约束
7.1 失败—观测—验证机制
7.1.1 失败优先定义原则
系统设计时，不能只定义成功路径，还必须优先定义失败路径。

任何核心流程在进入实现前，都必须明确：

失败条件
失败传播方式
回退策略
重试边界
用户可见结果

7.1.2 可观测性内建原则
日志、错误码、状态追踪、关键事件记录与性能指标采集，必须作为架构内建能力进入骨架。

不能依赖事后补日志。
7.1.3 验证先行原则
任何核心骨架、核心流程、核心边界在进入大规模实现前，都必须有对应验证方式。

若一个原则无法被验证，则该原则在实现中极易失效。
7.2 版本与迁移原则
任何核心接口、核心数据模型、核心配置模型一旦变化，都必须回答：

旧版本如何兼容
现有数据如何迁移
失败后如何回退

凡沉淀到磁盘、数据库、缓存、同步链路或导入导出格式中的结构，都负有版本责任。
7.3 幂等与重复执行原则
任何可能被重复触发、重复调用、重复投递、重复恢复执行的核心流程，都必须具备幂等性或显式去重机制。
7.4 并发与时序一致性原则
任何核心状态在被多个流程同时读取、修改、同步或回写时，都必须明确：

谁先
谁后
谁覆盖谁
冲突如何解决

7.5 示例：RSS 阅读器
对“刷新订阅源”流程，系统必须同时定义：

抓取成功路径
网络失败、解析失败、部分写入失败路径
关键状态是否可追踪
同一文章是否会重复入库
已读状态是否会被刷新或同步错误覆盖
批量刷新时的性能瓶颈位置


8. 运行裁量约束
8.1 默认保守原则
在信息不足或不确定性较高时，系统默认选择更保守、更稳定、更容易回退的方案，而不是更激进、更复杂、耦合更深的方案。
8.2 退出与删除原则
系统不仅要定义对象如何产生和增长，也必须定义对象如何停用、删除、迁移、失效和清理。

任何可被创建的核心对象，都必须有清晰退出路径。

9. 启动约束
9.1 实现最低原则
系统不得在草案尚未达到最低成熟度之前进入正式动工阶段。

任何实现都必须建立在最低限度分析与骨架确认已经完成的前提下。
9.2 最低成熟条件
进入实现阶段的最低条件是：

系统本体已得到基本澄清
主骨架与主边界已得到初步确认
明显错误方向与异质能力已完成初步排除
首版目标与主闭环已明确
当前实现不会直接污染未来主干

9.3 探索性实现的限制
探索性验证可以存在，但不得：

伪装为正式骨架实现
未经收敛直接沉淀为长期主干


10. 纠偏与治理约束
10.1 证伪—纠偏—审批机制
10.1.1 证伪即退出原则
任何方向、能力轴、抽象、边界划分或骨架判断，一旦经分析被认定为错误、失效或已被证伪，就必须立即退出。

不得因沉没成本、既有投入、历史惯性或实现便利而继续占据主骨架。
10.1.2 骨架即时纠偏原则
系统在任何阶段都不承认“骨架一旦形成便不得修正”。

只要管理员 / USER 经分析认定某一方向错误、某一骨架判断被证伪，或某一骨架存在明显不完善漏洞，就必须立即进入骨架纠偏流程。
这里的“立即”定义为：立即启动分析、审查与决策流程，而不是绕过审查直接改动主骨架。
10.1.3 骨架变更审批原则
任何骨架级变更都必须先提交具体分析报告，并由管理员 / USER 阅读后明确批准，方可执行。

未经审批，不得擅自修改：

主骨架
核心边界
核心对象关系
主能力轴
关键接口结构

骨架变更分析报告至少必须包含：

变更原因
当前骨架存在的问题或已被证伪之处
变更后可获得的收益
变更后新增的风险与代价
对既有模块、状态模型、数据模型、配置模型的影响
是否涉及迁移、兼容、回退与验证
若不变更，会持续产生什么后果

10.2 决策复核与反证原则
任何管理员 / USER 的骨架级判断、方向性判断或变更性判断，都不因其审批地位而自动免于复核。

只要存在充分理由认为该判断可能失误、偏颇、证据不足或忽略了关键代价，就必须提交高质量、客观、完整的复核分析报告，对该判断进行反证性审查。
复核分析报告至少必须包含：

当前判断成立的依据
当前判断可能忽略的问题
若维持原判断，可获得的收益
若维持原判断，可能承受的风险与代价
若修正原判断，可获得的收益
若修正原判断，可能引入的新问题
当前争议究竟属于实现问题、模块问题、边界问题还是骨架问题

复核的目的不是削弱管理员 / USER 的决策权，而是保证骨架级决策始终接受高质量反证与双面分析，从而持续逼近更高质量的系统判断。

11. 附录约定
11.1 实例附录
正文中仅保留最小必要实例。

更详细的 RSS 阅读器映射说明应移入附录单独维护。



hermes-agent
Mon, 11 May 2026 00:00:00 GMT
Github Repo
Hermes Agent Github Repo
docker-compose
networks:
    1panel-network:
        external: true

services:
    hermes:
        container_name: hermes-agent
        image: nousresearch/hermes-agent:latest
        restart: unless-stopped
        command: ["gateway", "run"]
        env_file:
            - .env
        environment:
            - TZ=${TIME_ZONE}
            - HERMES_UID=${HERMES_UID}
            - HERMES_GID=${HERMES_GID}
            - HERMES_DASHBOARD=${HERMES_DASHBOARD}
            - HERMES_DASHBOARD_HOST=${HERMES_DASHBOARD_HOST}
            - HERMES_DASHBOARD_PORT=${HERMES_DASHBOARD_PORT}
            - HERMES_DASHBOARD_TUI=${HERMES_DASHBOARD_TUI}
            - HERMES_INFERENCE_PROVIDER=${HERMES_INFERENCE_PROVIDER}
            - API_SERVER_ENABLED=${API_SERVER_ENABLED}
            - API_SERVER_HOST=${API_SERVER_HOST}
            - API_SERVER_KEY=${API_SERVER_KEY}
            - API_SERVER_CORS_ORIGINS=${API_SERVER_CORS_ORIGINS}
            - OPENROUTER_API_KEY=${OPENROUTER_API_KEY}
            - OPENAI_API_KEY=${OPENAI_API_KEY}
            - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
            - GOOGLE_API_KEY=${GOOGLE_API_KEY}
            - GEMINI_API_KEY=${GEMINI_API_KEY}
            - DEEPSEEK_API_KEY=${DEEPSEEK_API_KEY}
            - TAVILY_API_KEY=${TAVILY_API_KEY}
            - TELEGRAM_BOT_TOKEN=${TELEGRAM_BOT_TOKEN}
            - TELEGRAM_ALLOWED_USERS=${TELEGRAM_ALLOWED_USERS}
        labels:
            createdBy: Apps
        networks:
            - 1panel-network
        ports:
            - ${HOST_IP}:${HERMES_API_HOST_PORT}:8642
            - ${HOST_IP}:${HERMES_DASHBOARD_HOST_PORT}:9119
        volumes:
            - ./data:/opt/data
        shm_size: 1g
        healthcheck:
            test: ["CMD", "python3", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8642/health', timeout=3)"]
            interval: 30s
            timeout: 5s
            start_period: 20s
            retries: 3

env
TIME_ZONE=Asia/Shanghai
HOST_IP=127.0.0.1

HERMES_API_HOST_PORT=8642
HERMES_DASHBOARD_HOST_PORT=9119

HERMES_UID=10000
HERMES_GID=10000

HERMES_DASHBOARD=1
HERMES_DASHBOARD_HOST=0.0.0.0
HERMES_DASHBOARD_PORT=9119
HERMES_DASHBOARD_TUI=1
HERMES_INFERENCE_PROVIDER=deepseek

API_SERVER_ENABLED=true
API_SERVER_HOST=0.0.0.0
API_SERVER_KEY=换成至少8位以上的强随机字符串
API_SERVER_CORS_ORIGINS=*

# 模型服务 Key：至少填一个
OPENROUTER_API_KEY=
OPENAI_API_KEY=
ANTHROPIC_API_KEY=
GOOGLE_API_KEY=
GEMINI_API_KEY=
DEEPSEEK_API_KEY=

# Web-Search Key
TAVILY_API_KEY=

# Telegram，可选
TELEGRAM_BOT_TOKEN=
# 直接搜索 @userinfobot 查询
TELEGRAM_ALLOWED_USERS=

不要直接把 9119 / 8642 暴露到公网，建议 HOST_IP=127.0.0.1 后再通过 1Panel 反代访问。
如果想要让Hermes管理更多文件夹/文件，就用volumes挂载进容器



openclaw
Mon, 11 May 2026 00:00:00 GMT
Github Repo
OpenClaw Github Repo
docker-compose
networks:
    1panel-network:
        external: true

services:
    openclaw-gateway:
        container_name: openclaw-gateway
        image: ${OPENCLAW_IMAGE}
        restart: unless-stopped
        init: true
        env_file:
            - .env
        environment:
            HOME: /home/node
            TERM: xterm-256color
            TZ: ${TIME_ZONE}
            OPENCLAW_CONFIG_DIR: /home/node/.openclaw
            OPENCLAW_WORKSPACE_DIR: /home/node/.openclaw/workspace
            OPENCLAW_GATEWAY_TOKEN: ${OPENCLAW_GATEWAY_TOKEN}
            OPENCLAW_ALLOW_INSECURE_PRIVATE_WS: ${OPENCLAW_ALLOW_INSECURE_PRIVATE_WS}
            OPENCLAW_DISABLE_BONJOUR: ${OPENCLAW_DISABLE_BONJOUR}
            OPENAI_API_KEY: ${OPENAI_API_KEY}
            ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY}
            OPENROUTER_API_KEY: ${OPENROUTER_API_KEY}
            GOOGLE_API_KEY: ${GOOGLE_API_KEY}
            GEMINI_API_KEY: ${GEMINI_API_KEY}
            DEEPSEEK_API_KEY: ${DEEPSEEK_API_KEY}
        labels:
            createdBy: Apps
        networks:
            - 1panel-network
        ports:
            - ${HOST_IP}:${OPENCLAW_GATEWAY_HOST_PORT}:18789
            - ${HOST_IP}:${OPENCLAW_BRIDGE_HOST_PORT}:18790
        volumes:
            - ./config:/home/node/.openclaw
            - ./workspace:/home/node/.openclaw/workspace
        cap_drop:
            - NET_RAW
            - NET_ADMIN
        security_opt:
            - no-new-privileges:true
        extra_hosts:
            - "host.docker.internal:host-gateway"
        command:
            [
                "node",
                "dist/index.js",
                "gateway",
                "--bind",
                "${OPENCLAW_GATEWAY_BIND}",
                "--port",
                "18789",
            ]
        healthcheck:
            test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:18789/healthz').then((r)=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"]
            interval: 30s
            timeout: 5s
            start_period: 20s
            retries: 5

    openclaw-cli:
        image: ${OPENCLAW_IMAGE}
        env_file:
            - .env
        network_mode: "service:openclaw-gateway"
        init: true
        stdin_open: true
        tty: true
        environment:
            HOME: /home/node
            TERM: xterm-256color
            TZ: ${TIME_ZONE}
            BROWSER: echo
            OPENCLAW_CONFIG_DIR: /home/node/.openclaw
            OPENCLAW_WORKSPACE_DIR: /home/node/.openclaw/workspace
            OPENCLAW_GATEWAY_TOKEN: ${OPENCLAW_GATEWAY_TOKEN}
            OPENCLAW_ALLOW_INSECURE_PRIVATE_WS: ${OPENCLAW_ALLOW_INSECURE_PRIVATE_WS}
            OPENAI_API_KEY: ${OPENAI_API_KEY}
            ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY}
            OPENROUTER_API_KEY: ${OPENROUTER_API_KEY}
            GOOGLE_API_KEY: ${GOOGLE_API_KEY}
            GEMINI_API_KEY: ${GEMINI_API_KEY}
            DEEPSEEK_API_KEY: ${DEEPSEEK_API_KEY}
        volumes:
            - ./config:/home/node/.openclaw
            - ./workspace:/home/node/.openclaw/workspace
        cap_drop:
            - NET_RAW
            - NET_ADMIN
        security_opt:
            - no-new-privileges:true
        entrypoint: ["node", "dist/index.js"]
        depends_on:
            - openclaw-gateway

env
TIME_ZONE=Asia/Shanghai
HOST_IP=127.0.0.1

OPENCLAW_IMAGE=ghcr.io/openclaw/openclaw:latest
OPENCLAW_GATEWAY_HOST_PORT=18789
OPENCLAW_BRIDGE_HOST_PORT=18790
OPENCLAW_GATEWAY_BIND=lan
OPENCLAW_GATEWAY_TOKEN=换成强随机字符串
OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=
OPENCLAW_DISABLE_BONJOUR=1

# 模型服务 Key：至少填一个，或在 onboard 中配置 OAuth / API key
OPENAI_API_KEY=
ANTHROPIC_API_KEY=
OPENROUTER_API_KEY=
GOOGLE_API_KEY=
GEMINI_API_KEY=
DEEPSEEK_API_KEY=

初始化
首次启动前，先生成 token：
openssl rand -hex 32

然后执行 onboarding：
docker compose run --rm --no-deps --entrypoint node openclaw-gateway dist/index.js onboard --mode local --no-install-daemon
docker compose run --rm --no-deps --entrypoint node openclaw-gateway dist/index.js config set --batch-json '[{"path":"gateway.mode","value":"local"},{"path":"gateway.bind","value":"lan"},{"path":"gateway.controlUi.allowedOrigins","value":["http://localhost:18789","http://127.0.0.1:18789"]}]'
docker compose up -d

后台启动后，日常命令通过 openclaw-cli 执行：
docker compose run --rm openclaw-cli dashboard --no-open
docker compose run --rm openclaw-cli channels login
docker compose run --rm openclaw-cli channels add
docker compose run --rm openclaw-cli doctor

不要直接把 18789 暴露到公网，建议 HOST_IP=127.0.0.1 后再通过 1Panel 反代访问。
如果想让 OpenClaw 管理更多文件夹/文件，就用 volumes 挂载进容器。



OpenClaw Skills 推荐
Tue, 14 Apr 2026 00:00:00 GMT
OpenClaw Skills 推荐
本文主要参考：ClawHub 与 OpenClaw Skills 官方文档
0. 最短安装建议
如果你不想一上来装太多，可以先按下面这个顺序来：

先装 skill-vetter：先审查，再决定装不装其他 skill。
开发场景优先装 github。
查资料场景优先装 tavily-search。
想让 agent 更稳一点，再装 using-superpowers。
真的需要网页自动化时，再装 agent-browser。

一个够用的起步组合：
clawhub install skill-vetter
clawhub install github
clawhub install tavily-search
clawhub install using-superpowers

如果你明确需要浏览器自动化，再补：
clawhub install agent-browser


1. skills 装到哪里了
很多人装完以后第一反应都是：为什么我明明装了，但当前 session 里没看到？
clawhub 默认会优先装到当前工作目录的 ./skills；如果你已经配置了 OpenClaw workspace，也可能落到对应 workspace。
常见位置：

当前 agent / 当前项目专用：/skills
全局共享：~/.openclaw/skills

所以如果一个 agent 能看到 skill，另一个 agent 看不到，通常不是没装上，而是 skill 装到了某个 workspace，而不是全局位置。

2. 先看安全，再看功能
ClawHub 是公开技能市场，不是所有 skill 都由 OpenClaw 官方维护。
官方文档明确提到：

安装前会显示将写入的文件与依赖变更。
社区举报达到阈值的 skill 会被自动隐藏。
对会联网、会执行命令、会控制浏览器的 skill，应该先审查再安装。

另外，ClawHub 在 2026 年 2 月 出现过恶意 skill 事件，所以现在选 skill 不能只看“功能强不强”，还要看 权限边界是不是清楚、用途是不是单纯。
所以我自己的习惯是：
clawhub install skill-vetter

先装它，再去看别的。

3. 常用命令
clawhub search "github"
clawhub install skill-vetter
clawhub update --all
clawhub whoami
clawhub login


4. 我最推荐先看的 6 个 skill
1）skill-vetter
页面：spclaudehome/skill-vetter
最适合先装。它的价值不在“帮你做业务”，而在“帮你判断别的 skill 能不能装”。如果你准备长期用 OpenClaw，或者准备在 VPS / 常驻环境里装第三方 skill，这个几乎应该算基础设施。
2）github
页面：steipete/github
如果你主要用 OpenClaw 做开发，这个基本就是第一优先级，最适合 仓库浏览、Issue、PR、工程协作流 这类真实开发任务。
3）tavily-search
页面：arun-8687/tavily-search
定位很直接：补强网页搜索。涉及“最近更新”“最新资料”“官网怎么写”这类任务时，它的价值很高。
4）using-superpowers
页面：zlc000190/using-superpowers
它更像一套 行为纪律框架。适合“agent 不是不会做，而是步骤不稳、顺序不对、容易乱试”的场景。
5）prompt-engineering-expert
页面：TomsTools11/prompt-engineering-expert
适合经常自己写 prompt、系统提示、工作流提示的人。它更适合“把任务描述整理得更可执行”。
6）ontology
页面：oswalpalash/ontology
适合研究、知识组织、结构化笔记和概念建模。如果你希望 OpenClaw 不只是“回一句话”，而是帮你整理概念、搭知识框架，这类 skill 很有价值。

5. 哪些有用，但不是所有人都先装
humanizer
页面：biostartechnology/humanizer
适合写邮件、润色说明文、降低明显的 AI 味；如果你主要做工程任务，它就不是第一优先级。
marketing-skills
页面：jchopard69/marketing-skills
更偏市场、运营、活动文案、业务内容场景；如果你的 OpenClaw 更偏内容生产而不是工程协作，它会更有价值。

6. 哪些我建议谨慎安装
agent-browser
页面：TheSethRose/agent-browser
这个 skill 很强，但权限也更高。它适合 网页浏览、页面导航、登录后台、表单操作；但也因为能接触更多网页状态和浏览器交互，所以不建议新手一上来就把它当常驻基础 skill。
比较稳的做法：

先确认你确实需要浏览器自动化
先用 skill-vetter 审查
尽量放在受控环境里使用

self-improving-agent
页面：pskoett/self-improving-agent
它的优点很明显：能让 agent 通过反思和规则沉淀逐步改进；但问题也很明显：它影响的是 长期行为方式，一旦效果不好，排查通常比普通 skill 更麻烦。
所以我的建议是：

它不是不能装
但不建议一开始就常驻启用
更适合你已经有稳定工作流之后再上


7. 按场景怎么选
开发协作
优先：github
补充：using-superpowers、prompt-engineering-expert
查资料 / 跟踪最新信息
优先：tavily-search
补充：agent-browser（仅在确实需要网页自动化时）
知识整理 / 研究 / 结构化笔记
优先：ontology
补充：prompt-engineering-expert
文案润色 / 对外表达
优先：humanizer
市场 / 运营 / 活动内容
优先：marketing-skills

8. 新手最容易踩的几个坑
1）装完 skill，不一定当前会话立刻生效
很多时候需要重新开一个 OpenClaw session，或者至少重新进入对应 workspace，skill 才会被重新扫描到。
2）你以为装的是“全局”，其实装的是“当前 workspace”
如果你在某个项目目录里执行 clawhub install ...，它很可能是装到当前项目 / 当前 agent 的 workspace 里，而不是全局位置。
3）第三方 skill 的敏感配置不是“小事”
有些 skill 需要 env、apiKey、浏览器登录态或者外部服务 token。这类配置直接决定了 skill 能访问什么资源，所以要特别注意放置位置和最小权限。

9. 推荐节奏
推荐安装顺序：

skill-vetter
github 或 tavily-search
using-superpowers
prompt-engineering-expert 或 ontology
agent-browser
self-improving-agent

原因很简单：

前 3 个最容易立即产生收益
中间 2 个更偏“增强工作质量”
最后 2 个更强，但也更容易把系统复杂度拉高

10. 什么时候该用共享 skill，什么时候该用单 agent skill
如果这个 skill 是你几乎所有 agent 都会反复用到的，比如 skill-vetter、tavily-search 这种通用型能力，放到全局共享位置会更省事。
如果这个 skill 只服务某一个工作区，比如某个特定项目、某个特定业务流程，放到该 agent 自己的 workspace 里会更干净，也更容易隔离风险。
一个很实用的经验是：

通用能力，尽量共享
高权限能力，尽量按 agent 隔离
和具体项目强绑定的 skill，不要一股脑全局化

参考

ClawHub
OpenClaw Skills Overview
OpenClaw Skills Safety
Tom's Hardware: 恶意 ClawHub skill 事件
The Verge: OpenClaw 技能市场安全问题报道




easytier
Tue, 14 Apr 2026 00:00:00 GMT
Github Repo
EasyTier Github Repo
docker-compose
services:
    easytier:
        container_name: easytier
        image: easytier/easytier:latest
        hostname: ${EASYTIER_HOSTNAME}
        labels:
            createdBy: Apps
            com.centurylinklabs.watchtower.enable: 'true'
        restart: unless-stopped
        network_mode: host
        cap_add:
            - NET_ADMIN
            - NET_RAW
        environment:
            - TZ=${TIME_ZONE}
        devices:
            - /dev/net/tun:/dev/net/tun
        volumes:
            - ${EASYTIER_DATA_PATH}:/root
            - /etc/machine-id:/etc/machine-id:ro
        command: >
            -d
            --network-name ${EASYTIER_NETWORK_NAME}
            --network-secret ${EASYTIER_NETWORK_SECRET}
            ${EASYTIER_PEERS}
            ${EASYTIER_IPV4}

env
TIME_ZONE=Asia/Shanghai

EASYTIER_HOSTNAME=ali_ecs
EASYTIER_DATA_PATH=/etc/easytier

EASYTIER_NETWORK_NAME=
EASYTIER_NETWORK_SECRET=

# 可填多个 -p，留空也可以
EASYTIER_PEERS=-p tcp://public.easytier.top:11010

# 例如: EASYTIER_IPV4=-i 10.144.144.2
# 不需要就留空
EASYTIER_IPV4=

防火墙记得放开端口11010



miaomiaowu
Tue, 14 Apr 2026 00:00:00 GMT
Github Repo
miaomiaowu Github Repo
docker-compose
networks:
    1panel-network:
        external: true

services:
    miaomiaowu:
        container_name: miaomiaowu
        image: ghcr.io/iluobei/miaomiaowu:latest
        user: root
        restart: unless-stopped
        environment:
            - TZ=${TIME_ZONE}
            - PORT=${MMW_CONTAINER_PORT}
            - DATABASE_PATH=/app/data/traffic.db
            - LOG_LEVEL=${MMW_LOG_LEVEL}
            - JWT_SECRET=${MMW_JWT_SECRET}
        labels:
            createdBy: Apps
        networks:
            - 1panel-network
        ports:
            - ${HOST_IP}:${MMW_HOST_PORT}:${MMW_CONTAINER_PORT}
        volumes:
            - ./data:/app/data
            - ./subscribes:/app/subscribes
            - ./rule_templates:/app/rule_templates
        healthcheck:
            test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:8080/"]
            interval: 30s
            timeout: 3s
            start_period: 5s
            retries: 3

env
TIME_ZONE=UTC
HOST_IP=127.0.0.1
MMW_HOST_PORT=13200
MMW_CONTAINER_PORT=8080
MMW_LOG_LEVEL=info
MMW_JWT_SECRET=换成一串足够长的随机字符串




sing-box
Tue, 14 Apr 2026 00:00:00 GMT
Github Repo
sing-box Github Repo
前置工作
目录结构
准备一个目录，构建好如下结构：
/opt/singbox
├─ .env
├─ docker-compose.yml
├─ templates/
│  └─ config.json.template
├─ generated/
│  └─ config.json
├─ data/
├─ www/
└─ ssl/
   └─ example.com/
      ├─ fullchain.pem
      └─ privkey.pem

证书准备
VLESS + Reality 不依赖你自己的证书域名做握手目标
Hysteria2 / Naive / TUIC 都依赖你自己的真实 TLS 证书
所以你需要把 example.com 对应的证书放到：
/opt/singbox/ssl/example.com/fullchain.pem
/opt/singbox/ssl/example.com/privkey.pem

密钥和凭据
1）生成 Reality 密钥对
TLS 文档明确写了：Reality 服务端要用 private_key，客户端要用 public_key，都由 sing-box generate reality-keypair 生成。short_id 是必填，长度是 0 到 8 位十六进制字符串。(Sing Box)
docker run --rm ghcr.io/sagernet/sing-box generate reality-keypair

你会拿到两项：


PrivateKey → 服务端配置里用


PublicKey → 客户端配置里用


自己再准备一个 8 位十六进制 short_id，例如：
openssl rand -hex 8

2）生成 UUID
给 VLESS 和 TUIC 各准备一个 UUID：
cat /proc/sys/kernel/random/uuid
cat /proc/sys/kernel/random/uuid

3）生成强密码
给 Hysteria2、Naive、TUIC 分别准备长随机密码：
openssl rand -base64 24
openssl rand -base64 24
openssl rand -base64 24
openssl rand -base64 24

其中 Hysteria2 我建议准备两个：

password
obfs.password

templates/config.json.template
把下面内容保存为 /opt/singbox/templates/config.json.template：
{
  "log": {
    "level": "${LOG_LEVEL}",
    "timestamp": true
  },
  "inbounds": [
    {
      "type": "vless",
      "tag": "vless-reality-in",
      "listen": "::",
      "listen_port": ${VLESS_PORT},
      "users": [
        {
          "name": "vless-user",
          "uuid": "${VLESS_UUID}",
          "flow": "xtls-rprx-vision"
        }
      ],
      "tls": {
        "enabled": true,
        "server_name": "${REALITY_HANDSHAKE_SERVER}",
        "min_version": "1.3",
        "max_version": "1.3",
        "reality": {
          "enabled": true,
          "handshake": {
            "server": "${REALITY_HANDSHAKE_SERVER}",
            "server_port": ${REALITY_HANDSHAKE_PORT}
          },
          "private_key": "${REALITY_PRIVATE_KEY}",
          "short_id": [
            "${REALITY_SHORT_ID}"
          ],
          "max_time_difference": "1m"
        }
      }
    },
    {
      "type": "hysteria2",
      "tag": "hy2-in",
      "listen": "::",
      "listen_port": ${HY2_PORT},
      "up_mbps": ${HY2_UP_MBPS},
      "down_mbps": ${HY2_DOWN_MBPS},
      "obfs": {
        "type": "salamander",
        "password": "${HY2_OBFS_PASSWORD}"
      },
      "users": [
        {
          "name": "hy2-user",
          "password": "${HY2_PASSWORD}"
        }
      ],
      "ignore_client_bandwidth": false,
      "tls": {
        "enabled": true,
        "certificate_path": "${TLS_CERT_PATH}",
        "key_path": "${TLS_KEY_PATH}",
        "min_version": "1.3",
        "max_version": "1.3",
        "alpn": [
          "h3"
        ]
      },
      "masquerade": {
        "type": "file",
        "directory": "/srv/www"
      }
    },
    {
      "type": "naive",
      "tag": "naive-in",
      "listen": "::",
      "listen_port": ${NAIVE_PORT},
      "users": [
        {
          "username": "${NAIVE_USERNAME}",
          "password": "${NAIVE_PASSWORD}"
        }
      ],
      "tls": {
        "enabled": true,
        "certificate_path": "${TLS_CERT_PATH}",
        "key_path": "${TLS_KEY_PATH}"
      }
    },
    {
      "type": "tuic",
      "tag": "tuic-in",
      "listen": "::",
      "listen_port": ${TUIC_PORT},
      "users": [
        {
          "name": "tuic-user",
          "uuid": "${TUIC_UUID}",
          "password": "${TUIC_PASSWORD}"
        }
      ],
      "congestion_control": "${TUIC_CONGESTION_CONTROL}",
      "auth_timeout": "3s",
      "zero_rtt_handshake": false,
      "heartbeat": "10s",
      "tls": {
        "enabled": true,
        "certificate_path": "${TLS_CERT_PATH}",
        "key_path": "${TLS_KEY_PATH}",
        "min_version": "1.3",
        "max_version": "1.3",
        "alpn": [
          "h3"
        ]
      }
    }
  ],
  "outbounds": [
    {
      "type": "direct",
      "tag": "direct"
    },
    {
      "type": "block",
      "tag": "block"
    }
  ],
  "route": {
    "final": "direct"
  }
}

env
TZ=UTC

HOST_IP=0.0.0.0

VLESS_PORT=17000
HY2_PORT=26000
NAIVE_PORT=35000
TUIC_PORT=48000

SERVER_DOMAIN=example.com
REALITY_HANDSHAKE_SERVER=www.microsoft.com
REALITY_HANDSHAKE_PORT=443

VLESS_UUID=
REALITY_PRIVATE_KEY=
REALITY_PUBLIC_KEY=
REALITY_SHORT_ID=

HY2_PASSWORD=
HY2_OBFS_PASSWORD=
HY2_UP_MBPS=200
HY2_DOWN_MBPS=200

NAIVE_USERNAME=naive-user
NAIVE_PASSWORD=

TUIC_UUID=
TUIC_PASSWORD=
TUIC_CONGESTION_CONTROL=cubic

LOG_LEVEL=warn

TLS_CERT_PATH=/etc/ssl/sing-box/fullchain.pem
TLS_KEY_PATH=/etc/ssl/sing-box/privkey.pem

docker-compose
networks:
  1panel-network:
    external: true

services:
  singbox-config:
    image: alpine:3.20
    container_name: singbox-config
    restart: "no"
    env_file:
      - .env
    volumes:
      - ./templates:/templates:ro
      - ./generated:/generated
    command: >
      sh -c "
      apk add --no-cache gettext &&
      envsubst < /templates/config.json.template > /generated/config.json &&
      echo 'generated /generated/config.json'
      "
    networks:
      - 1panel-network

  sing-box:
    image: ghcr.io/sagernet/sing-box:latest
    container_name: sing-box
    restart: unless-stopped
    depends_on:
      singbox-config:
        condition: service_completed_successfully
    env_file:
      - .env
    ports:
      - ${HOST_IP}:${VLESS_PORT}:${VLESS_PORT}/tcp
      - ${HOST_IP}:${HY2_PORT}:${HY2_PORT}/udp
      - ${HOST_IP}:${NAIVE_PORT}:${NAIVE_PORT}/tcp
      - ${HOST_IP}:${TUIC_PORT}:${TUIC_PORT}/udp
    volumes:
      - ./generated:/etc/sing-box:ro
      - ./data:/var/lib/sing-box
      - ./www:/srv/www:ro
      - ./ssl/example.com:/etc/ssl/sing-box:ro
    command: -D /var/lib/sing-box -C /etc/sing-box run
    read_only: true
    tmpfs:
      - /tmp
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    networks:
      - 1panel-network

singbox-config 只负责把模板渲染成 generated/config.json
防火墙记得放开对应端口



v2rayA
Tue, 14 Apr 2026 00:00:00 GMT
Github Repo
v2rayA Github Repo
docker-compose
networks:
    1panel-network:
        external: true

services:
    v2raya:
        container_name: v2raya
        image: mzz2017/v2raya:latest
        restart: always
        environment:
            - TZ=${TIME_ZONE}
            - V2RAYA_LOG_FILE=${V2RAYA_LOG_FILE}
        labels:
            createdBy: Apps
        networks:
            - 1panel-network
        ports:
            - ${HOST_IP}:${V2RAYA_PANEL_PORT}:2017
            - ${HOST_IP}:${V2RAYA_SOCKS_PORT}:20170
            - ${HOST_IP}:${V2RAYA_HTTP_PORT}:20171
            - ${HOST_IP}:${V2RAYA_TRANSPARENT_PORT}:20172
        volumes:
            - ${V2RAYA_DATA_PATH}:/etc/v2raya

env
HOST_IP=127.0.0.1
TIME_ZONE=UTC
V2RAYA_PANEL_PORT=2017
V2RAYA_SOCKS_PORT=20170
V2RAYA_HTTP_PORT=20171
V2RAYA_TRANSPARENT_PORT=20172

V2RAYA_LOG_FILE=/tmp/v2raya.log
V2RAYA_DATA_PATH=/etc/v2raya

防火墙记得放开端口20171并且v2rayA控制面板设置里面打开端口转发，目的是为了让其它容器或内网其它设备可以正常访问
如果镜像版本太老可能无法识别最新协议，需要手动本地拉取最新镜像后上传至服务器



CC Switch
Mon, 13 Apr 2026 00:00:00 GMT
CC Switch 使用指南
1. CC Switch 是什么
Github Repo
CC Switch (Cloud/Code Switch) 是一个可视化的终端配置管理工具，目前主要支持 Claude Code、Codex 以及 Gemini CLI。

补充：截至 2026-04-13，仓库 README 展示的当前版本为 v3.9.1。

核心能力：

多环境切换：一键覆写 Claude/Codex/Gemini 的配置文件，毫秒级生效。
MCP 统一管理：在一个面板管理所有 CLI 的 MCP Server，支持一键开关与同步。
Prompts 系统：可视化管理 CLAUDE.md、AGENTS.md 和 GEMINI.md 系统提示词。
Skills 仓库：自动扫描管理Skills，并支持一键安装 GitHub 上的 Claude Skills。


2. 安装与更新

支持 macOS, Windows, Linux 全平台 (基于 Tauri v2)。

2.1 macOS
推荐使用 Homebrew 安装：
# 1. 订阅 Tap
brew tap farion1231/ccswitch

# 2. 安装
brew install --cask cc-switch

更新：
brew upgrade --cask cc-switch

2.2 Windows
推荐使用 scoop 安装:
scoop install --cask cc-switch

更新：
scoop upgrade --cask cc-switch

其它安装方式：

安装包：下载 .msi 安装程序。
便携版：下载 .zip 解压即用。
前往 GitHub Releases 下载

2.3 Linux

Arch Linux (AUR):paru -S cc-switch-bin


Flatpak:flatpak install --user ./CC-Switch-v{version}-Linux.flatpak
flatpak run com.ccswitch.desktop


其他发行版: 提供 .deb, .rpm 和 .AppImage。


3. 快速上手
3.1 添加配置 (Add Provider)

提示：使用前请确保已安装对应的 CLI 工具（如 npm i -g @anthropic-ai/claude-code），否则无法生效。

CC Switch 的核心概念是 Provider（配置预设）。

点击主界面右上角的 Add Provider。
选择模版：

Claude Official: 官方 OAuth 登录模式。
OpenAI Compatible: 适用于 Codex 或使用中转服务的 Claude Code (如 DeepSeek, PackyCode)。
Gemini Official: Google 官方 API。


填写对应的 API Key 和 Base URL。

注意：中转服务地址通常需包含 /v1 后缀（如 https://api.example.com/v1）。



3.2 一键切换

在列表中选中你想要使用的环境。
点击 Enable（或在系统托盘直接选择）。
生效机制：

CC Switch 会自动修改对应 CLI 的配置文件（如 ~/.claude/settings.json 或 ~/.codex/auth.json）。
通常需要重启终端或对应客户端：例如重新运行 claude、codex 或 Gemini CLI 后生效。




4. 深度功能解析
4.1 MCP 管理中心 (Unified MCP)
不再需要手动编辑复杂的 JSON 配置文件。CC Switch 提供了一个统一的面板来管理所有工具的 MCP Server。

多工具同步：你可以定义一个 MCP Server（如 filesystem），并勾选它同步到 Claude 和 Codex。
配置隔离：也可以为特定工具设置独享的 MCP。
导入导出：支持从现有的 claude.json 导入配置。

4.2 Prompts (系统提示词) 管理
针对不同项目或角色，快速切换系统级指令。

文件映射：

Claude -> CLAUDE.md
Codex -> AGENTS.md
Gemini -> GEMINI.md


特色功能：内置 Markdown 编辑器，支持实时预览。切换 Preset 时，会自动备份当前目录下的原有文件，防止误覆盖。

4.3 Skills 技能库 (v3.7+)

自动发现：输入 GitHub 仓库地址（如 User/Repo），自动扫描其中的 Skills。
一键安装：将扫描到的工具直接安装到 ~/.claude/skills/ 目录，Claude Code 启动时会自动加载。


5. 配置文件与数据架构
5.1 数据存储
CC Switch 采用 SQLite + JSON 双层架构 (v3.8+)：

核心数据 (SSOT): ~/.cc-switch/cc-switch.db 存储所有 Provider、MCP、Prompts 和 Skills 数据。
本地设置: ~/.cc-switch/settings.json 存储窗口状态、路径等设备级配置。

5.2 云同步 (Cloud Sync)
实现多台电脑配置一致：

进入 Settings -> Custom Configuration Directory。
选择你的云同步目录（如 Dropbox, OneDrive, iCloud Drive）。
应用重启后，数据将迁移至该目录，在其他电脑指向同一目录即可实现同步。

5.3 CLI 配置文件路径参考
CC Switch 修改的目标文件如下，了解这些有助于排查问题：



工具
配置文件路径
说明




Claude Code
~/.claude/settings.json / ~/.claude.json
存储配置、认证与 MCP


Codex
~/.codex/auth.json
存储认证信息


Codex
~/.codex/config.toml
存储 MCP Server


Gemini CLI
~/.gemini/.env
存储 API Key


Gemini CLI
~/.gemini/settings.json
存储认证模式和 MCP




6. 常见问题
Q: 切换后 Claude Code 报错 401？

检查 Base URL 是否正确。如果使用中转，通常需要带上 /v1（如 https://api.example.com/v1）。
如果是官方模式，尝试重新进行 OAuth 授权。

Q: 什么是 Deep Link？

CC Switch 支持 ccswitch:// 协议。
你可以将配置导出为链接分享给同事，对方点击链接即可一键导入复杂的 API 和 MCP 配置。




Claude Code
Mon, 13 Apr 2026 00:00:00 GMT
Claude Code 使用指南
1. Claude Code 是什么
GitHub Repo
Claude Code（命令 claude）是一个终端内的 Agent：读代码、改文件、执行命令、做 git 工作流。

补充：Claude Code 的官方 GitHub 仓库现在已经公开，仓库内也直接包含 plugins/、.claude/commands/、examples/hooks/ 等官方示例。

官方文档：

https://code.claude.com/docs/en/overview
https://code.claude.com/docs/zh-CN/overview
https://code.claude.com/docs/en/setup
https://code.claude.com/docs/en/cli-reference


2. 安装与更新

官方说明：NPM 安装已标记为 deprecated，优先使用 Native 安装脚本 / Homebrew / WinGet。

2.1 安装
macOS / Linux / WSL
Homebrew (macOS/Linux)：
brew install --cask claude-code

直接安装：
curl -fsSL https://claude.ai/install.sh | bash

Windows
scoop包管理器：
scoop install claude-code

WinGet (Windows)：
winget install Anthropic.ClaudeCode

直接安装：
irm https://claude.ai/install.ps1 | iex

Windows CMD：
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

NPM (Deprecated)：
npm install -g @anthropic-ai/claude-code


Node.js 18+ 仅对 NPM 安装方式必需。

2.3 更新
claude update


Homebrew/WinGet/Scoop 安装不会自动更新：用 brew upgrade claude-code 或 winget upgrade Anthropic.ClaudeCode 或 scoop update claude-code。

2.4 健康检查
claude -v
claude doctor


3. 快速开始
3.1 在项目目录启动
cd /path/to/your/project
claude

3.2 常用指令
/init
/login
/logout
/config
/permissions
/model
/status
/mcp
/agents
/hooks
/plugin
/reload-plugins
/terminal-setup
/sandbox
/compact
/rewind

3.3* 非官方中转 / 代理 API（LLM Gateway）

适用场景：企业网关 / 自建代理 / LiteLLM 等，把 Claude Code 的请求转发到你自己的网关。

A. 最小配置：鉴权 + Base URL
方式 1：环境变量（示例以 LiteLLM 的 Anthropic unified endpoint 为例）：
export ANTHROPIC_AUTH_TOKEN=sk-your-gateway-key
export ANTHROPIC_BASE_URL=https://litellm-server:4000

Windows PowerShell：
$env:ANTHROPIC_AUTH_TOKEN="sk-your-gateway-key"
$env:ANTHROPIC_BASE_URL="https://litellm-server:4000"

方式 2：写进 settings.json（/config 里也可以改）：
{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "sk-your-gateway-key",
    "ANTHROPIC_BASE_URL": "https://litellm-server:4000"
  }
}


网关侧要求：至少兼容 Anthropic Messages 端点（/v1/messages、/v1/messages/count_tokens），并正确转发 anthropic-beta / anthropic-version 等头；否则部分功能可能不可用。

B. 兼容性开关（常见）
当网关对 anthropic-beta 头不兼容时：
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1

C. Provider pass-through（按需）
Bedrock via gateway（示例为 LiteLLM pass-through）：
export ANTHROPIC_BEDROCK_BASE_URL=https://litellm-server:4000/bedrock
export CLAUDE_CODE_SKIP_BEDROCK_AUTH=1
export CLAUDE_CODE_USE_BEDROCK=1

Vertex via gateway（示例为 LiteLLM pass-through）：
export ANTHROPIC_VERTEX_BASE_URL=https://litellm-server:4000/vertex_ai/v1
export ANTHROPIC_VERTEX_PROJECT_ID=your-gcp-project-id
export CLOUD_ML_REGION=us-east5
export CLAUDE_CODE_SKIP_VERTEX_AUTH=1
export CLAUDE_CODE_USE_VERTEX=1

D. 第三方模型直连（Anthropic API 兼容）

前提：第三方服务提供 Anthropic Messages 格式（通常为 .../anthropic + /v1/messages）。

DeepSeek（示例）：
export ANTHROPIC_AUTH_TOKEN=sk-your-deepseek-key
export ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic
export ANTHROPIC_MODEL=deepseek-chat

智谱 GLM（示例）：
export ANTHROPIC_AUTH_TOKEN=your_zhipu_api_key
export ANTHROPIC_BASE_URL=https://open.bigmodel.cn/api/anthropic
export ANTHROPIC_DEFAULT_SONNET_MODEL=glm-4.6
export ANTHROPIC_DEFAULT_HAIKU_MODEL=glm-4.5-air


4. 交互基础（核心用法）
4.1 @file 引用文件
在输入中用 @ 触发路径补全并引用文件。
4.2 !cmd 直接跑命令
在输入行以 ! 开头执行命令并把输出带入上下文：
!git status
!npm test

4.3 会话续跑
claude -c
claude -r "session-id-or-name" "prompt"


5. 配置体系（settings / 作用域）
Claude Code 的设置有 scope，优先级：Managed > CLI args > Local > Project > User。
5.1 Settings 文件



Scope
文件
说明




User
~/.claude/settings.json
个人全局设置


Project
.claude/settings.json
团队共享（建议提交 git）


Local
.claude/settings.local.json
个人覆盖（通常 gitignore）


Managed
managed-settings.json
组织级强制策略（系统目录下发）



5.2 状态与 MCP

~/.claude.json：偏好、OAuth 会话、用户/本地 MCP、每项目状态与缓存等。
.mcp.json：项目级 MCP（适合提交 git）。

5.3 记忆文件 (CLAUDE.md)

项目：CLAUDE.md 或 .claude/CLAUDE.md
本地：CLAUDE.local.md


6. 权限控制（最小模板）
在项目内创建 .claude/settings.json：
{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(pnpm *)",
      "Bash(yarn *)",
      "Bash(git status)",
      "Bash(git diff *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  }
}


7. MCP（模型上下文协议）
常用命令：
claude mcp list
claude mcp get github
claude mcp remove github

添加远程 HTTP server：
claude mcp add --transport http notion https://mcp.notion.com/mcp

添加本地 stdio server：
claude mcp add --transport stdio airtable --env AIRTABLE_API_KEY=YOUR_KEY \
  -- npx -y airtable-mcp-server


8. Skills / Agents / Rules
8.1 Skills（技能系统）
技能文件：.claude/skills//SKILL.md（项目级）或 ~/.claude/skills//SKILL.md（全局）。
最小模板：
---
name: review
description: Review changes with a strict checklist
disable-model-invocation: true
---

1. 运行 `!git diff` 并总结风险点。
2. 检查是否有 secrets / 破坏性变更。
3. 给出可执行的修复建议。

使用：在 Claude Code 里输入 /review。

兼容说明：旧的 .claude/commands/*.md 仍可用；同名 skill 会优先于 command。

8.2 Subagents（子代理）
/agents 管理子代理（Project: .claude/agents/，User: ~/.claude/agents/）。内置常用：Explore（只读搜索）、Plan（plan mode 辅助）。
最小示例：
---
name: code-reviewer
description: Proactively review code for quality and security
tools: Read, Glob, Grep, Bash
model: sonnet
---

Review changes. Focus on security, correctness, and edge cases.

8.3 Rules / Memory（CLAUDE.md + .claude/rules）
启动时加载 CLAUDE.md（含 ~/.claude/CLAUDE.md），并加载 .claude/rules/*.md 作为模块化规则。
常用结构：
./CLAUDE.md
./CLAUDE.local.md
./.claude/CLAUDE.md
./.claude/rules/*.md
~/.claude/CLAUDE.md

路径规则（可选）：
---
paths:
  - "src/api/**/*.ts"
---

- API 统一返回结构 ...

8.4 Hooks / Plugins（可选）
Hooks：用 /hooks 配置，写入 settings.json 的 hooks 字段；常用于格式化、阻止危险命令、在 compaction 后补充上下文。
Plugins：用于打包分发 skills/agents/hooks/MCP。

入口：插件目录下 .claude-plugin/plugin.json
本地调试：claude --plugin-dir ./my-plugin

补充：

官方 Anthropic marketplace claude-plugins-official 现在默认可直接使用。
安装/启用/禁用插件后，可执行 /reload-plugins 无需重启会话。
例如安装官方 GitHub 插件：

/plugin install github@claude-plugins-official


9. 常用 CLI 形态（速查）
claude                 # 交互式 REPL
claude "query"        # 带初始 prompt 进入 REPL
claude -p "query"     # 只打印结果（适合脚本）
cat file | claude -p "query"


10. 常用环境变量（速查）
这些也可以写进 settings.json 的 env 字段。



变量
用途




ANTHROPIC_API_KEY
API Key（X-Api-Key）


ANTHROPIC_AUTH_TOKEN
Bearer token（Authorization）


ANTHROPIC_MODEL
默认模型（alias 或 model name）


ANTHROPIC_BASE_URL
LLM gateway / 代理 base URL（Anthropic Messages 格式）


ANTHROPIC_DEFAULT_OPUS_MODEL
覆盖 opus 的默认模型名


ANTHROPIC_DEFAULT_SONNET_MODEL
覆盖 sonnet 的默认模型名


ANTHROPIC_DEFAULT_HAIKU_MODEL
覆盖 haiku 的默认模型名（ANTHROPIC_SMALL_FAST_MODEL 已 deprecated）


ANTHROPIC_CUSTOM_HEADERS
给所有请求追加自定义 HTTP header


HTTP_PROXY / HTTPS_PROXY / NO_PROXY
代理配置


CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
同时关闭自动更新/遥测/错误上报等非必要流量


NODE_EXTRA_CA_CERTS
追加企业 CA 证书（代理/网关环境常用）


CLAUDE_CODE_CLIENT_CERT / CLAUDE_CODE_CLIENT_KEY
mTLS 客户端证书/私钥


DISABLE_AUTOUPDATER=1
关闭自动更新


CLAUDE_CONFIG_DIR
自定义配置与数据目录


MCP_TIMEOUT / MCP_TOOL_TIMEOUT
MCP 启动/执行超时（ms）


MAX_MCP_OUTPUT_TOKENS
MCP 输出 token 上限


ENABLE_TOOL_SEARCH
MCP tool search（auto/auto:N/true/false）


CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1
禁用后台任务


CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION=false
关闭输入框提示补全


BASH_DEFAULT_TIMEOUT_MS / BASH_MAX_TIMEOUT_MS
Bash 默认/最大超时（ms）




11. Windows 备注

原生 Windows 运行：官方建议使用 Git Bash 或 WSL。
Git Bash 路径可用环境变量指定：

$env:CLAUDE_CODE_GIT_BASH_PATH="C:\Program Files\Git\bin\bash.exe"


本地 MCP 若依赖 npx，可能需要 cmd /c 包一层（详见 MCP 文档 Windows Warning）。




Cockpit Tools
Mon, 13 Apr 2026 00:00:00 GMT
Cockpit Tools 使用指南
1. Cockpit Tools 是什么
Github Repo
Cockpit Tools 是一个通用 AI IDE 账号管理工具。它不是新的 AI IDE，也不是新的 CLI，而是一个桌面侧“账号中控台”：

管理多平台 AI IDE 账号
查看配额/重置时间
一键切换当前活跃账号
支持部分平台多开实例并行工作
提供本地 WebSocket / 插件集成能力


截至 2026-04-13，我已用 gh api repos/jlcodes99/cockpit-tools/releases/latest 直接核对：最新 GitHub release 为 v0.21.2（2026-04-13）。

仓库当前 README 显示，已经不再只是早期的 Antigravity / Codex 工具，而是扩展为支持：

Antigravity
Codex
GitHub Copilot
Windsurf
Kiro
Cursor
Gemini Cli
CodeBuddy
CodeBuddy CN
Qoder
Trae
Zed

补充：

它本身并不直接“管理 OpenCode 账号”
但 README 中已经出现 OpenCode App Path 与 Codex 切号后自动重启 OpenCode 的联动设置，说明它开始兼顾 OpenCode 生态的实际配套需求


2. 安装与更新

当前 README 明确把 手动下载 Releases 包 作为推荐安装方式；Homebrew 主要是 macOS 方案，Arch Linux 额外提供 AUR。

2.1 手动下载（推荐）
前往：

GitHub Releases

常见安装包：

macOS：.dmg（Apple Silicon / Intel）
Windows：.msi（推荐）或 .exe
Linux：.deb、.rpm 或 .AppImage

2.2 macOS（Homebrew）
brew tap jlcodes99/cockpit-tools https://github.com/jlcodes99/cockpit-tools
brew install --cask cockpit-tools

如果遇到 macOS “App is damaged”：
brew install --cask --no-quarantine cockpit-tools

如果提示应用已存在：
rm -rf "/Applications/Cockpit Tools.app"
brew install --cask cockpit-tools

或者直接强制覆盖：
brew install --cask --force cockpit-tools

2.3 Arch Linux（AUR）
# 源码构建包
yay -S cockpit-tools

# 预编译二进制包
yay -S cockpit-tools-bin


仓库 README 当前写的是 yay 示例，但按 AUR 习惯，paru 同样可用。

2.4 macOS 打不开（额外修复）
sudo xattr -rd com.apple.quarantine "/Applications/Cockpit Tools.app"


3. 快速上手
3.1 第一次启动后先做什么
建议顺序：

打开 Cockpit Tools
先进入 Settings
检查各平台的可执行路径是否自动识别成功
再添加/导入账号
最后按平台启用自动刷新或 WebSocket 集成

3.2 核心使用流
以 Codex / Antigravity / Copilot 这类平台为例，Cockpit Tools 的典型用法是：

导入账号（OAuth / Token / JSON / 本地状态导入，具体取决于平台）
查看当前账号配额与 reset time
在账号列表里切换活跃账号
如有需要，直接启动对应平台客户端
如果你有多项目并行需求，再启用多实例

3.3 Dashboard（总览页）
当前 README 里 Dashboard 的定位很明确：

多平台账号状态总览
配额与重置时间可视化
一键刷新
一键唤醒
统一进度条视图

如果你手里账号很多，Cockpit Tools 的价值主要就在这里：

把原本分散在多个 IDE / CLI / 浏览器页里的“账号状态”收拢到一个桌面面板里。

4. 核心能力
4.1 多账号切换
这是最核心的能力。
不同平台支持的导入方式略有不同，但总体上都围绕：

OAuth
Token / JSON 导入
本地登录态导入

你不再需要手工反复替换本地配置文件，而是直接在桌面面板切号。
4.2 配额监控
仓库 README 当前强调的不是“只有账号切换”，而是：

配额剩余量
reset time
plan 类型识别
某些平台的额外 credit / budget / cycle 信息

这对多账号调度很关键，因为切号不是目的，配额可见性才是切号决策的依据。
4.3 多实例并行
当前 README 已明确支持多实例的平台包括：

Antigravity
Codex
GitHub Copilot（VS Code 侧）
Windsurf
Kiro
Cursor
CodeBuddy
CodeBuddy CN
Qoder
Trae

共同特征：

每个实例可绑定不同账号
实例目录/用户数据目录隔离
可独立启动/停止/强制停止
适合同时跑多个项目

这类设计的底层逻辑很简单：

不是“让一个 IDE 支持多账号同时在线”，而是通过实例隔离把账号和项目运行时分开。
4.4 唤醒任务（Wake-up Tasks）
目前 README 里对 Antigravity 的支持最深，包括：

唤醒任务
配额重置周期预热
设备指纹管理
多实例

如果你主要是 Antigravity 用户，这块会是 Cockpit Tools 的重点价值区。
4.5 本地 WebSocket / 插件集成
README 明确提到：

WebSocket 默认绑定 127.0.0.1
默认端口 19528
可在 Settings 中关闭或改端口

这意味着 Cockpit Tools 不只是一个“手动点按钮”的桌面应用，也可以作为本地 companion service 被插件或扩展读取状态。

5. 配置与数据（你要知道它改了哪里）
5.1 本地数据存储
README 当前写得比较直接：

~/.antigravity_cockpit：Antigravity 账号、配置、WebSocket 状态等
~/.codex：Codex 官方当前登录态（如 auth.json）
~/.gemini：Gemini Cli 本地 session 文件
本地应用数据目录 com.antigravity.cockpit-tools：多平台索引数据等

这说明它不是“纯展示工具”，而是真实会写本地状态的账号管理器。
5.2 常见设置项
README 的设置说明里，当前最值得记住的几类：

显示语言 / 主题
关闭窗口行为
各平台自动刷新间隔
数据目录
各平台 App Path
WebSocket 开关与端口
OpenCode App Path
Codex 切号后自动重启 OpenCode

补充：v0.21.2 新增了本地备份/导入包与备份管理器，也就是现在可以在设置页里做“仅账号 / 仅配置 / 两者一起”的备份与恢复。
5.3 建议的默认策略
如果你只是想稳定用，不想折腾：

自动刷新：5-10 分钟
WebSocket：不用插件就关闭
App Path：优先让它自动识别
多实例：有明确并行项目需求再开


6. 安全与风险
Cockpit Tools 当前 README 的安全表述核心是：

这是本地桌面工具，不是云端托管服务
主要数据保存在你的机器上
开网络主要发生在 OAuth、刷新 token、拉取配额、检查更新等场景

实战建议：

不需要插件联动时，关闭 WebSocket
不要直接分享完整用户目录
备份时先处理 token / auth 文件
在公用电脑上使用后及时移除账号并退出


7. FAQ（常见问题）
7.1 这和 CC Switch 的区别是什么？
两者都属于“多工具账号/配置管理”方向，但 Cockpit Tools 当前更偏：

桌面总控台
配额可视化
多实例并行
对 Antigravity / Codex / Copilot / Windsurf / Kiro / Cursor 等平台的账号管理

如果你的核心诉求是“多账号调度 + 配额总览 + 平台多开”，Cockpit Tools 更贴近这个方向。
7.2 它支持 OpenCode 吗？
严格说，当前 README 里它的主支持对象不是 OpenCode 账号本身。

但已经能看到：

OpenCode App Path
Auto-restart OpenCode on Codex switch

所以更准确的说法是：它主要管理 Codex 等账号，但已经开始兼容 OpenCode 联动场景。
7.3 WebSocket 要不要开？
如果你不用本地插件集成，建议默认关闭。

理由很简单：减少常驻暴露面，也减少无意义的后台占用。
7.4 多实例适合什么场景？
适合：

多个项目并行
多账号隔离运行
测试不同环境/不同额度账号

不适合：

只偶尔切一次账号
不需要同时开多个 IDE / CLI


8. 参考链接
https://github.com/jlcodes99/cockpit-tools
https://github.com/jlcodes99/cockpit-tools/releases
https://github.com/jlcodes99/cockpit-tools#readme




OpenCode
Mon, 13 Apr 2026 00:00:00 GMT
OpenCode 使用指南
1. OpenCode 是什么
Github Repo
OpenCode（命令通常为 opencode）是一个面向代码库的 AI 编码agent

截至 2026-04-13，GitHub 发布页显示的最新版本为 v1.4.3（2026-04-10）。


2. 安装与更新

下面按系统选择一种安装方式即可。

2.1 macOS / Linux
A. 官方安装脚本
curl -fsSL https://opencode.ai/install | bash

B. Homebrew（推荐）
brew install anomalyco/tap/opencode

C. Homebrew（官方 formula，更新通常比 tap 慢）
brew install opencode

2.2 Arch Linux（Paru）
paru -S opencode-bin

如需稳定仓库版本，也可使用：
sudo pacman -S opencode

2.3 Windows
A. Chocolatey
choco install opencode

B. Scoop
scoop install opencode

C. NPM（推荐，全局安装）
npm install -g opencode-ai

2.4 其他安装方式
mise use -g opencode
nix run nixpkgs#opencode

2.5 Desktop App（Beta）
OpenCode 现在还提供桌面版应用，可从以下地址下载：

GitHub Releases
opencode.ai/download


更新：使用你的包管理器进行更新（brew upgrade / choco upgrade / scoop update / npm update -g opencode-ai
等）。


3. 快速开始

打开命令行窗口cmd

3.1 在项目目录启动
cd /path/to/your/project
opencode

也可以直接：
opencode /path/to/your/project

启动后会进入终端交互界面（TUI）。
3.2 连接模型（必须）
在 TUI 输入：
/connect

按提示选择 provider，并填写/登录获取 API Key。
3.2*第三方中转 / 代理 API（OpenAI-Compatible Relay）

适用场景：你使用的是“第三方中转/聚合/企业网关/LiteLLM/自建代理”等，提供 OpenAI 兼容的接口（通常是 /v1 + chat/completions 风格）。

OpenCode 的做法是：先在 opencode.json/jsonc 里把该中转服务配置成一个“自定义 Provider”,再在 TUI 用 /connect 保存 API Key（凭据）。
B 第一步：在 opencode.json 中配置 baseURL + models
在全局目录$USER\.config\opencode项目根目录创建/修改 opencode.jsonc：
{
  "$schema": "https://opencode.ai/config.json",

  "provider": {
    "relay": {
      "npm": "@ai-sdk/openai-compatible",
      //claude就写@ai-sdk/anthropic
      "name": "My Relay (OpenAI-Compatible)",
      //名字随便取，后面对应地方也要修改
      "options": {
        "baseURL": "https://你的中转域名/v1"
      },
      "models": {
        "gpt-5.1": { "name": "GPT-5.2 (via relay)" },
        //填写模型名称，后面的name是自定义的
        "claude-sonnet-4-5": { "name": "Claude Sonnet 4.5 (via relay)" }
      }
    }
  },

  "model": "My Relay (OpenAI-Compatible)/GPT-5.2"
  //选择你进入页面后的默认model
}

B 第二步：在 TUI 里添加凭据（/connect → Other）

打开 TUI：opencode
输入：/connect
在列表输入你刚刚填写的名称，找到后并选择
输入你的中转 API Key（如 sk-...）

配置完成后回到 TUI：

输入 /models，你会看到 “My Relay (OpenAI-Compatible)” 下的模型并可切换。


C) 第三步（可选）：如果中转需要“自定义 Header”而不是标准 Authorization
有些中转不是 Authorization: Bearer ...，而是例如：

api-key: xxx
X-API-Key: xxx
Authorization: Bearer <自定义token>

这时你可以在 options.headers 里加自定义头。官方示例支持 options.headers。
示例（把 Key 放在环境变量里更安全）：
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "relay": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "My Relay",
      "options": {
        "baseURL": "https://你的中转域名/v1",
        "headers": {
          "api-key": "{env:RELAY_API_KEY}"
        }
      },
      "models": {
        "gpt-4.1": { "name": "GPT-4.1 (relay)" }
      }
    }
  },
  "model": "relay/gpt-4.1"
}

然后在 shell 中设置环境变量（举例）：


macOS/Linux：
export RELAY_API_KEY="你的key"



Windows PowerShell：
setx RELAY_API_KEY "你的key"




官方也给出了 options.apiKey 与 env 变量写法、以及 headers 的示例，你可以按自己的中转要求选择：

如果你已用 /connect 存了 key，通常不必再写 options.apiKey；
如果你的中转只认自定义 header（例如 api-key），就按上面这样在 headers 里显式设置。


3.3 列出并切换模型
在 TUI 输入：
/models

然后选择你要用的模型（通常会显示 provider/model）。
3.4 项目初始化
在 TUI 输入：
/init

它会生成（或更新）当前目录下的AGENTS.md，用于帮助 OpenCode 更快理解项目结构与约定。建议提交到 Git。
补充：当前官方文档对 /init 的描述更接近“引导式创建/更新 AGENTS.md”。

4. TUI 交互基础（核心用法）
4.1 会话与上下文

OpenCode 会把对话当作“会话（session）”来管理
你可以随时切换/恢复不同会话，避免不同任务互相污染上下文

常用命令：
/sessions


4.2 引用文件 @file
在消息里使用 @ 搜索并引用文件/路径，让模型把文件内容加入上下文。
示例：
请解释 @src/auth/index.ts 的认证流程，并指出入口函数与调用链。

建议用法：

先让它概览，再逐个 @ 关键文件深挖
大文件优先引用关键片段所在文件或模块


4.3 执行命令 !cmd
在消息中以 ! 开头，OpenCode 会执行 shell 命令并把输出带回对话。
示例：
!npm test

常见用途：

复现 bug：!pytest -q / !npm test / !go test ./...
运行 linter：!eslint . / !ruff check .
打印目录结构：!ls -la / !tree -L 3


强烈建议配合“权限控制”使用（见 6.3）。


4.4 常用斜杠命令 /...
以下命令在 TUI 里输入即可（括号内为常用别名）：

/help：显示帮助对话框
/connect：连接/管理 provider 凭据
/models：列出与切换模型
/sessions (/resume, /continue)：列出/切换历史会话
/new (/clear)：开启全新会话
/init：生成/更新 AGENTS.md
/compact (/summarize)：压缩当前会话（总结长上下文以节省 Token）
/undo：撤销上一次代码修改（依赖 Git）
/redo：重做撤销的修改
/share / /unshare：分享/取消分享当前会话
/editor：调用外部编辑器（如 VS Code）编写长输入
/export：将对话导出为 Markdown 文件
/details：切换工具执行细节显示
/thinking：切换思考内容显示
/themes：切换界面主题
/exit (/quit, /q)：退出


4.5 快捷键大全（核心效率）
OpenCode 使用 Leader 键（默认 Ctrl+x）来触发快速操作：



快捷键
功能
快捷键
功能




Ctrl+x n
开启新会话
Ctrl+x u
撤销修改


Ctrl+x l
列出历史会话
Ctrl+x r
重做修改


Ctrl+x m
切换模型
Ctrl+x s
分享会话


Ctrl+x i
初始化项目
Ctrl+x e
外部编辑器


Ctrl+x t
切换主题
Ctrl+x q
退出


Ctrl+x b
切换侧边栏
Ctrl+x y
复制消息


Ctrl+x a
Agent 列表
Ctrl+x g
会话时间线



基础操作与导航：

Tab / Shift+Tab：在 Plan（规划） 与 Build（构建） 模式间切换。
Ctrl+x → / Ctrl+x ←：在 父会话 与 子会话（由 @general 等触发）之间快速切换。
Shift+Enter / Ctrl+j：在输入框内换行。
PgUp / PgDown：向上/下翻页。
Ctrl+Alt+u / Ctrl+Alt+d：向上/下翻 半页。
Home / End：跳至对话最顶部或最底部。
Escape：中断当前的 AI 输出。


5. Agent 模式与子代理
OpenCode 并非单一的对话框，它通过不同的 Agent 协同工作。
5.1 Plan vs Build 模式

Plan Mode (🧠)：只分析，不改代码。适合架构设计、逻辑推演或大规模重构前的方案评估。
Build Mode (🔨)：直接修改文件。根据指令进行编码、修复 Bug。
最佳实践：复杂任务先在 Plan 模式确认方案，满意后再切到 Build 模式说“开始执行”。

5.2 子代理（Subagents）
在对话中使用 @ 可以召唤特定功能的子代理：

@general：用于处理需要多步推理、跨文件搜索的复杂任务。

示例：“@general 在整个项目中搜索所有使用了 localStorage 的地方并总结用途。”
示例：“@general 分析项目依赖，找出是否存在循环引用。”




补充：当前官方 README 明确写出的内置子代理是 @general；@explore 不再适合作为“稳定内置能力”来介绍。


6. 基本流程（固定）

cmd opencode 或者vscode opencode 扩展（推荐）启动 TUI
/connect 连接 provider（填 key 或登录）
/models 选择模型
/init 更新 AGENTS.md
/sessions 选择历史对话
/new 新对话


6. 配置体系（opencode.json/jsonc）
OpenCode 支持项目级与全局配置文件：

opencode.json
opencode.jsonc（允许注释，推荐）


6.1 配置加载顺序
常见的覆盖逻辑（后者覆盖前者的冲突项）：

组织级默认（远程）
全局配置（如 ~/.config/opencode/opencode.json）
环境变量指定 OPENCODE_CONFIG
项目根目录 opencode.json/opencode.jsonc
项目 .opencode/ 下的 agents/commands/plugins 等扩展内容（如你使用了）


建议：团队统一的默认策略放全局或组织层；项目特殊策略放项目根。


6.2 常用配置项
在项目根创建 opencode.jsonc：
{
  "$schema": "https://opencode.ai/config.json",

  // 默认使用的主模型
  "model": "anthropic/claude-sonnet-4-5",

  // 工具权限（建议先保守，逐步放开）
  "permission": {
    "edit": "ask",
    "bash": "ask",
    "webfetch": "allow"
  }
}

6.3 权限控制（强烈建议启用）
OpenCode 常见高风险能力：

写入/修改文件（edit）
执行命令（bash）
网络抓取（webfetch）

建议在初期把关键权限设为 ask：

allow：允许自动执行
deny：禁止
ask：每次执行前询问（推荐默认）

团队项目建议：

bash 默认 ask，避免误删/误改环境
edit 默认 ask，避免大范围变更未审
webfetch 可 allow 或 ask（看你是否允许拉取外部信息）

7.Rules (规则系统)
Rules 允许你通过 AGENTS.md 文件为项目定义长期遵循的指令（类似于 Cursor 的 .cursorrules）。
7.1 AGENTS.md 层级

项目级：存放在项目根目录。仅对该项目生效。
全局级：存放在 ~/.config/opencode/AGENTS.md。对所有项目生效（适合存放个人编程偏好）。

7.2 引入外部规则
在 opencode.jsonc 中，你可以通过 instructions 数组引用现有的 Markdown 文档作为规则：
{
  "instructions": [
    "CONTRIBUTING.md",
    "docs/coding-standards.md",
    ".cursor/rules/*.md" // 支持通配符导入 Cursor 规则
  ]
}


8.MCP (模型上下文协议)
MCP 允许 OpenCode 挂载外部工具（如 Google Search, GitHub API, SQL 查询等）。
8.1 本地 MCP 服务器
在配置文件的 mcp 字段下定义：
"mcp": {
  "my-local-tool": {
    "type": "local",
    "command": ["npx", "-y", "@modelcontextprotocol/server-everything"],
    "enabled": true
  }
}

8.2 远程 MCP 服务器
支持 OAuth 认证，初次使用时会在浏览器弹出授权：
"mcp": {
  "sentry": {
    "type": "remote",
    "url": "https://mcp.sentry.dev/mcp",
    "enabled": true
  }
}


9.SKILLS (技能系统)
Skills 是可复用的指令片段，通过 SKILL.md 文件定义。代理会自动发现这些技能并按需加载。
9.1 创建技能
路径：.opencode/skills//SKILL.md
---
name: git-release
description: 用于起草标准化的 Git Release 说明和版本号更新建议
---
## 指令
1. 检查当前已合并的 PR。
2. 按照 SemVer 建议版本号。
3. 生成 gh release create 命令。

9.2 权限管理
你可以控制哪些技能被允许、拒绝或需要询问：
"permission": {
  "skill": {
    "git-release": "allow",
    "experimental-*": "ask",
    "*": "deny"
  }
}


10. 进阶指南与最佳实践
10.1 避坑与性能优化

上下文超限：如果项目极大，务必使用 /compact。同时在 opencode.jsonc 中合理配置 ignore 列表（默认遵循 .gitignore）。
图片支持：直接将图片（报错截图、设计稿）拖入终端，OpenCode 即可理解图片内容。
国产模型适配：对于火山引擎、DeepSeek 等国内 Provider，推荐使用 OpenAI-Compatible Relay 模式配置（详见 3.2*）。

10.2 常用 Shell 技巧
使用 ! 执行命令时，输出会直接进入上下文：

!tree -L 2：让 AI 快速预览目录结构。
!git diff HEAD：让 AI 总结你刚才手动做的修改。
!npm test -- --grep "auth"：运行特定测试并让 AI 修复报错。

10.4 提示词（Prompt）优化要素
为了让 OpenCode 给出最精准的代码，建议在消息中包含以下要素：

具体文件：使用 @ 引用所有相关文件（如 @api.ts @types.ts），避免 AI 瞎猜。
明确目标：说清楚“要做什么”，而不是“帮我改下”。（例：“重构 request 函数，使用 async/await 替代 Promise”）。
丰富上下文：提供完整的错误信息（直接粘贴或拖入截图）、期望的运行结果。
约束条件：指定技术栈或代码风格（例：“请遵循项目现有的函数式编程风格”）。

10.5 调试与日志
如果遇到 OpenCode 自身运行异常，可以使用调试模式启动以查看详细日志：
# 开启 debug 级别日志并重定向到文件
opencode --log-level debug > opencode-debug.log




everything-claude-code
Mon, 13 Apr 2026 00:00:00 GMT
everything-claude-code 使用指南

信息来源：该仓库的 README.md / README.zh-CN.md、rules/README.md、以及作者的 shortform/longform guide（已通过联网抓取核对）。

1. everything-claude-code 是什么
GitHub Repo
everything-claude-code（简称 ECC）是一套“可直接落地”的 Claude Code 配置集合，目标是把 Claude Code 变成可复用的工程工作流：

补充：ECC 近几个版本已经不再只面向 Claude Code，本体仍叫 everything-claude-code，但当前 README 已明确扩展到 Claude Code、Cursor、OpenCode、Codex 等多工具使用场景。


Agents（子代理）
Skills（技能/工作流）
Commands（斜杠命令）
Hooks（生命周期/工具钩子自动化）
Rules（始终遵循的规则集，按语言分层）
MCP 配置示例（可选）

适合人群：你已经在用 Claude Code，但希望把“提示词经验”沉淀为可复用资产，并引入更标准的计划、TDD、审查、验证闭环。

2. 前置要求

已安装 Claude Code CLI。
版本要求：这篇文章原先记录的 v2.1.0+ 已偏旧；当前更稳妥的理解是应使用支持 marketplace / plugins / agents / hooks 的新版本 Claude Code。

检查版本：
claude --version


3. 快速开始（推荐：安装插件 + 安装 Rules）
3.1 安装插件（Claude Code 内执行）
在 Claude Code 交互界面输入：
/plugin marketplace add affaan-m/everything-claude-code

/plugin install everything-claude-code@everything-claude-code

补充：仓库近版本也开始强调 GitHub Marketplace 入口，ECC Tools 已可作为 marketplace 插件分发。
如果你更偏好直接改配置，也可以在 ~/.claude/settings.json 写入（示例以仓库 README 为准）：
{
  "extraKnownMarketplaces": {
    "everything-claude-code": {
      "source": {
        "source": "github",
        "repo": "affaan-m/everything-claude-code"
      }
    }
  },
  "enabledPlugins": {
    "everything-claude-code@everything-claude-code": true
  }
}

验证已安装：
/plugin list everything-claude-code@everything-claude-code

3.2 安装 Rules（仍然重要）
重要限制：即使现在插件体系已经更完整，rules 仍然通常需要你手动安装（或用仓库脚本安装），这一点没有本质改变。
先克隆仓库：
git clone https://github.com/affaan-m/everything-claude-code.git
cd everything-claude-code

方式 A：使用安装脚本（仓库推荐）
./install.sh typescript
./install.sh python
./install.sh golang

方式 B：手动复制（务必保留目录结构）

不要用 cp -r rules/* ~/.claude/rules/ 这种“扁平化复制”。ECC 的 rules/common/ 与 rules// 里会有同名文件；扁平化会覆盖并破坏 ../common/ 相对引用。

macOS/Linux：
mkdir -p ~/.claude/rules
cp -r rules/common ~/.claude/rules/common
cp -r rules/typescript ~/.claude/rules/typescript
cp -r rules/python ~/.claude/rules/python
cp -r rules/golang ~/.claude/rules/golang

Windows PowerShell（示例）：
New-Item -ItemType Directory -Force "$HOME\.claude\rules" | Out-Null
Copy-Item -Recurse -Force "rules\common" "$HOME\.claude\rules\common"
Copy-Item -Recurse -Force "rules\typescript" "$HOME\.claude\rules\typescript"
Copy-Item -Recurse -Force "rules\python" "$HOME\.claude\rules\python"
Copy-Item -Recurse -Force "rules\golang" "$HOME\.claude\rules\golang"

3.3 试跑一个命令
/plan "添加用户认证"


4. 主要内容一览（你装进来的是什么）
ECC 仓库整体可以理解为“工程化 Claude Code 的工具箱”，核心组件与常见落地位置如下：

agents/：子代理定义（用于委托 planner / architect / code-reviewer / security-reviewer / tdd-guide 等）
commands/：斜杠命令（把复杂工作流封装成可重复执行的 prompt）
skills/：技能/工作流知识库（更像“可复用 SOP + 参考实现”）
hooks/：钩子自动化（PreToolUse/PostToolUse/Stop 等阶段触发脚本）
rules/：规则集（永远遵守；按 common/ + 语言目录分层）
mcp-configs/：MCP server 配置样例（按需拷贝到你的 ~/.claude.json）

安装方式不同，文件落点不同：

插件安装：Claude Code 会把插件内容装入其插件目录；你主要“启用/禁用插件”和“手动安装 rules”。
手动安装：你需要把 agents/commands/skills/rules/hooks 复制到 ~/.claude/（或项目 .claude/）对应目录。


5. Rules（规则集，全量拆解）
ECC 的规则目录结构（必须按目录安装，而不是把文件拍平到一个目录）：

rules/common/：语言无关的“强约束”
rules/typescript/：TypeScript/JavaScript 扩展 common
rules/python/：Python 扩展 common
rules/golang/：Go 扩展 common

补充：ECC 后续版本还继续扩展了更多语言/栈支持，因此这里这三组语言规则更适合理解成“最基础、最常用的内置规则层”，而不是全部支持范围。

规则文件会互相引用（语言目录的规则会引用 ../common/...），因此必须保留目录结构。

5.1 common（8 个）
rules/common/agents.md

定义“什么时候应该委托给哪个 agent”（planner / code-reviewer / tdd-guide / architect 等）
强调独立任务应并行执行、多视角审查

rules/common/coding-style.md

不可变（immutability）是关键原则：尽量返回新对象/数组，不做原地修改
文件组织偏好“小文件多模块”：典型 200-400 行，建议上限 800 行
错误处理与输入校验必须显式

rules/common/git-workflow.md

Conventional Commits：feat/fix/refactor/docs/test/chore/perf/ci
PR 工作流：要求看全量 diff、写清测试计划
推荐流程：Plan → TDD → Review → Commit

rules/common/hooks.md

hooks 的类型说明：PreToolUse / PostToolUse / Stop
提醒“权限自动放行”要谨慎
*（作者原文里）强调 TodoWrite 的用途（你是否启用取决于你的工作流偏好）

rules/common/patterns.md

Skeleton project 思路：优先找“可复用骨架”而不是现场造轮子
Repository pattern / API response envelope 等通用模式

rules/common/performance.md

模型选择策略（Haiku / Sonnet / Opus）
上下文窗口管理：避免在窗口尾部做高风险重构
Plan mode + 深度思考（thinking）的开关与建议

rules/common/security.md

任何提交前的强制安全检查清单：密钥、输入校验、SQLi、XSS、CSRF、鉴权、限流、错误信息泄露等
一旦发现安全问题：立即停、走 security-reviewer 流程

rules/common/testing.md

80% 覆盖率最低门槛（单元/集成/E2E 都要有）
强制 TDD：RED → GREEN → IMPROVE，并要求覆盖边界条件与错误路径

5.2 TypeScript/JavaScript（5 个）
rules/typescript/coding-style.md

强化不可变更新（spread operator）
建议 async/await + try/catch
建议用 Zod 做 schema 校验
禁止生产代码里 console.log

rules/typescript/patterns.md

API Response 类型封装示例
React 自定义 hooks 模式示例（如 useDebounce）
Repository interface 模式示例

rules/typescript/testing.md

E2E 默认建议 Playwright
提及 agent：e2e-runner

rules/typescript/security.md

强调环境变量读取密钥、缺失时 fail fast
提及 agent：security-reviewer

rules/typescript/hooks.md

PostToolUse：Prettier 自动格式化、tsc 类型检查、console.log 告警
Stop：会话结束时做 console.log 审计

5.3 Python（5 个）
rules/python/coding-style.md

PEP 8 + 类型标注（function signature）
推荐不可变结构（@dataclass(frozen=True) / NamedTuple）
工具链建议：black / isort / ruff

rules/python/patterns.md

Protocol（鸭子类型接口）
dataclasses 作为 DTO
context manager / generator 的使用建议

rules/python/testing.md

pytest + 覆盖率命令示例
用 pytest.mark 分类（unit/integration）

rules/python/security.md

环境变量读密钥（示例用了 python-dotenv）
建议 bandit 做静态安全扫描

rules/python/hooks.md

PostToolUse：black/ruff 格式化、mypy/pyright 类型检查
警告 print()（建议用 logging）

5.4 Go（5 个）
rules/golang/coding-style.md

gofmt/goimports 强制
设计原则：accept interfaces, return structs；接口要小
错误必须 wrap 上下文（fmt.Errorf("...: %w", err)）

rules/golang/patterns.md

Functional options
小接口 + 就地定义
构造函数依赖注入

rules/golang/testing.md

标准 go test + table-driven tests
强制 -race
覆盖率 -cover

rules/golang/security.md

环境变量密钥 + 缺失时 fail fast
静态扫描 gosec
强制 context + timeout

rules/golang/hooks.md

PostToolUse：gofmt/goimports、go vet、staticcheck


6. Skills（技能/工作流，全量拆解）
技能在 ECC 里是“可复用的工作流与知识库”。它们通常：

给出“什么时候启用”
给出“步骤清单/检查点/示例代码”
部分技能会配套脚本（用于 hooks 触发或生成产物文件）

下面按主题把 skills/ 目录下的技能逐一拆开说明（共 32 个目录，按 main 分支内容整理）。
6.1 工程通用（架构/代码规范/检索/上下文管理）
skills/coding-standards

目的：通用代码规范（命名、不可变、错误处理、类型安全、React 写法、API 返回结构、目录组织等）
关键点：强调不可变；建议并行 async；强调输入校验；给出文件结构模板

skills/backend-patterns

目的：后端模式（REST API、Repository/Service 层、middleware、DB 查询优化、缓存、错误处理、鉴权、限流、队列、结构化日志等）
关键点：避免 N+1；缓存旁路（cache-aside）；统一错误处理；RBAC 示例

skills/frontend-patterns

目的：前端模式（React/Next.js 组件组合、compound components、自定义 hooks、状态管理、性能优化、表单、Error Boundary、动画、无障碍）
关键点：useMemo/useCallback；lazy load；虚拟列表；键盘导航与 focus 管理

skills/iterative-retrieval

目的：解决“子代理不知道该拿哪些上下文”的问题
方法：DISPATCH → EVALUATE → REFINE → LOOP（最多 3 轮），逐步收敛到高相关文件

skills/strategic-compact

目的：把 /compact 从“被动自动触发”变成“在里程碑节点主动触发”
典型节点：探索结束→开始实现；完成阶段性里程碑；准备切换任务上下文
hooks 方式：PreToolUse(Edit/Write) 统计调用次数，达到阈值提醒你 compact

skills/eval-harness

目的：Eval-Driven Development（把 eval 当作 AI 开发的“单元测试”）
关键概念：Capability eval / Regression eval；grader（代码/模型/人工）；pass@k vs pass^k
产物建议：把 eval 定义与报告存入 .claude/evals/

skills/configure-ecc

目的：交互式安装向导（帮你选择安装哪些 skills/rules，安装到 user-level 或 project-level，并做覆盖/合并提示）

6.2 质量与交付（TDD / 验证闭环 / 安全）
skills/tdd-workflow

目的：强制 TDD（覆盖率目标 80%+，覆盖 unit/integration/E2E）
关键点：先写用户旅程→生成用例→先跑失败→最小实现→再跑通过→重构→看覆盖率
给了 Jest/Vitest、API integration test、Playwright E2E 的示例结构

skills/verification-loop

目的：PR/交付前的质量闸口（build → typecheck → lint → tests → security → diff review）
输出建议：用固定格式写一份 VERIFICATION REPORT（PASS/FAIL + 待修复列表）

skills/security-review

目的：安全审查清单（Secrets、输入校验、SQLi、AuthZ、XSS、CSRF、Rate limit、日志脱敏、依赖安全等）
关键点：示例覆盖 TS/Next.js/Supabase/RLS、CSP、token 存储策略等

skills/security-scan

目的：用 AgentShield 扫描你的 Claude Code 配置（.claude/、MCP、hooks、agents 等）
常用命令：npx ecc-agentshield scan / --fix / --format json|markdown|html / --opus

6.3 持续学习（从会话沉淀可复用资产）
skills/continuous-learning

目的：会话结束时（Stop hook）总结“可复用模式”，自动沉淀为 learned skills
默认思路：会话足够长（如 10+ message）才抽取；落盘到 ~/.claude/skills/learned/
配置项：最小会话长度、抽取阈值、忽略模式、是否自动批准等

skills/continuous-learning-v2

目的：升级为“instinct（直觉）”的原子化学习体系（带置信度评分，可导入/导出，可聚类进化为 skills/commands/agents）
关键差异：用 PreToolUse/PostToolUse hooks 做 100% 观测；后台 observer（Haiku）做模式提取
主要目录：~/.claude/homunculus/observations.jsonl、instincts/personal|inherited、evolved/agents|skills|commands

6.4 语言/框架专项（把“最佳实践”写成可调用知识库）
Python：

skills/python-patterns：Pythonic idioms、PEP8、类型标注等
skills/python-testing：pytest、fixtures、mock、参数化、覆盖率要求
skills/django-patterns：Django/DRF 架构、ORM、缓存、middleware、生产实践
skills/django-security：Django 安全（CSRF/XSS/SQLi/部署安全等）
skills/django-tdd：pytest-django、factory_boy、DRF API 测试
skills/django-verification：Django 项目验证闭环（migrations、lint、tests、security、diff review）

Go：

skills/golang-patterns：Go 惯用法、并发、错误处理、项目组织等
skills/golang-testing：table-driven tests、bench、fuzz、覆盖率

Java/Spring：

skills/java-coding-standards：Java 代码规范（Optional/streams/异常/泛型/布局等）
skills/jpa-patterns：JPA/Hibernate 实体/关系/查询优化/事务/索引/分页等
skills/springboot-patterns：Spring Boot 架构/分层/缓存/异步/日志等
skills/springboot-security：Spring Security + Web 安全建议
skills/springboot-tdd：JUnit5/Mockito/MockMvc/Testcontainers/JaCoCo 的 TDD
skills/springboot-verification：Spring Boot 项目验证闭环（build、静态分析、测试覆盖率、安全扫描）

C++：

skills/cpp-testing：GoogleTest/CTest、覆盖率、sanitizers、排查 flaky tests

6.5 数据库与文档处理专项

skills/postgres-patterns：PostgreSQL/Supabase 相关的 schema/index/query/security 模式
skills/clickhouse-io：ClickHouse（MergeTree 家族、聚合表、物化视图、查询优化、监控、ETL/CDC 模式）
skills/nutrient-document-processing：Nutrient DWS API 文档处理（转换/OCR/抽取/脱敏/签名/表单填充等）

6.6 模板示例
skills/project-guidelines-example

这是“项目级 skill”的示例模板：技术栈、目录结构、API 规范、测试与部署流程等
你可以照此结构为自己的项目写一个“项目内专用 skill”，让 Claude Code 对你项目的约束更稳定


7. Commands（斜杠命令，全量拆解）
ECC 在 commands/ 下提供了一组可复用的斜杠命令（在 Claude Code 里以 /xxx 调用）。这些命令的核心价值是把“复杂提示词 + 固定流程”封装成稳定入口。

你看到的每个命令，其实就是一个可重复执行的工作流 prompt；其中一部分会显式调用某个 agent（例如 /plan 调 planner，/tdd 调 tdd-guide）。

7.1 命令清单（31 个）
/plan

作用：调用 planner 产出分阶段计划，并且“必须等待用户确认后才改代码”。
典型用法：/plan <需求描述>

/tdd

作用：调用 tdd-guide 强制 TDD（先写测试，再最小实现，再重构），目标覆盖率 80%+。
典型用法：/tdd <要实现/修复的功能>

/code-review

作用：对未提交变更做代码审查（按 CRITICAL/HIGH/MEDIUM/LOW 分级），包含安全项与质量项。

/verify

作用：执行验证闭环（build → typecheck → lint → tests → console.log 审计 → git status）。
参数：/verify quick|full|pre-commit|pre-pr（命令文件定义了这几种模式）。

/build-fix

作用：增量修复构建/类型错误；强调“一次只修一个错误→重跑验证”。

/test-coverage

作用：分析覆盖率并补齐缺失测试（通常与 /tdd、/verify 配合）。

/e2e

作用：调用 e2e-runner 生成/维护/执行 Playwright E2E 测试。

/checkpoint

作用：创建或验证一个“工作流检查点”（用于阶段性确认与回退/复盘）。

/eval

作用：管理 eval-driven development 工作流（定义/运行/报告 eval）。

/learn

作用：从当前会话抽取“值得沉淀为技能”的可复用模式。

/sessions

作用：管理 Claude Code session 历史（list/load/alias/info 等），会读写 ~/.claude/sessions/ 和 ~/.claude/session-aliases.json。

/setup-pm

作用：设置/检测首选包管理器（npm/pnpm/yarn/bun），支持全局与项目级，规则与优先级在命令文档内写得很清楚。

/skill-create

作用：本地解析 git 历史，提取项目习惯并生成 SKILL.md（可选同时生成 instincts 供 continuous-learning-v2 使用）。

Instinct 系列（continuous-learning-v2 配套）：

/instinct-status：查看已学习 instincts（带置信度、按 domain 分组）。
/instinct-import：导入 instincts。
/instinct-export：导出 instincts。
/evolve：把 instincts 聚类进化为 skills/commands/agents（命令文件会调用 instinct CLI）。

Go 专用：

/go-review：调用 go-reviewer 做 Go 代码审查。
/go-build：调用 go-build-resolver 修 Go build/vet 问题。
/go-test：Go 的 TDD 工作流（table-driven tests、race/coverage 等）。

Python 专用：

/python-review：调用 python-reviewer 做 Python 代码审查。

多模型编排（高级工作流）：

/orchestrate：顺序式多 agent 工作流（适合复杂任务分阶段推进）。
/multi-plan：多模型协作产计划。
/multi-execute：多模型协作执行与审计。
/multi-workflow：Research→Ideation→Plan→Execute→Optimize→Review 的全流程多模型协作。
/multi-frontend：偏前端的多模型流程。
/multi-backend：偏后端的多模型流程。

运维/多服务：

/pm2：扫描项目服务（Vite/Next/FastAPI/Go 等），生成 ecosystem.config.cjs 与一组 .claude/commands/pm2-*.md 便于启动/监控/查看日志（命令文件对 Windows 细节写得很具体）。

7.2 按场景的“推荐命令链”（可直接照抄）
新增功能（通用）：
/plan "..."
/tdd
/test-coverage
/code-review
/verify pre-pr

构建/类型报错优先绿灯：
/build-fix
/verify quick

准备提 PR：
/code-review
/verify pre-pr

E2E 测试补齐关键用户旅程：
/e2e
/verify full

把团队习惯沉淀为可复用资产：
/skill-create --commits 200
/learn

7.3 命令速查表（命令 → 调用对象 → 输入/输出要点）

说明：部分命令会显式调用 agent（例如 planner/tdd-guide/e2e-runner），其余多为固定工作流 prompt 或 Node 脚本。




命令
主要作用
主要调用
参数/备注




/plan
产出分阶段实施计划并等待确认
agent: planner
命令文档强调“未确认不得改代码”


/tdd
强制 TDD：先测试→最小实现→重构→覆盖率
agent: tdd-guide
覆盖率目标 80%+；E2E 另用 /e2e


/code-review
未提交变更的安全与质量审查
workflow（检查清单）
输出按 CRITICAL/HIGH/MEDIUM/LOW；CRITICAL/HIGH 应阻断提交


/verify
验证闭环（build/types/lint/tests/日志审计/git 状态）
workflow
支持 quick/full/pre-commit/pre-pr


/build-fix
增量修 build/类型错误（一次只修一个）
workflow
每次修复后重跑 build；同一错误多次失败应停下


/test-coverage
分析覆盖率并补齐缺失测试
workflow
常与 /tdd、/verify 配合


/e2e
生成/维护/执行 Playwright E2E
agent: e2e-runner
覆盖关键用户旅程；隔离 flaky tests


/checkpoint
创建/核对一个工作流检查点
workflow
用于阶段性确认/复盘


/eval
EDD：定义/运行/报告 eval
workflow（配合 skills/eval-harness）
适合把“成功标准”先写死


/learn
从当前会话提炼可复用模式
workflow（配合 continuous-learning）
更偏人工触发抽取


/sessions
会话历史管理（list/load/alias/info）
Node 脚本
读写 ~/.claude/sessions/、~/.claude/session-aliases.json


/setup-pm
设置/检测包管理器偏好
Node 脚本
优先级：env→项目→package.json→lock→全局→fallback


/skill-create
从 git 历史生成 SKILL.md（可选 instincts）
workflow
--commits/--output/--instincts


/instinct-status
查看 instincts（置信度/分组）
instinct CLI
continuous-learning-v2 配套


/instinct-import
导入 instincts
instinct CLI
continuous-learning-v2 配套


/instinct-export
导出 instincts
instinct CLI
continuous-learning-v2 配套


/evolve
instincts 聚类进化为技能/命令/代理
instinct CLI
continuous-learning-v2 配套


/go-review
Go 专用审查
agent: go-reviewer
并发/错误处理/性能/惯用法


/go-build
Go build/vet 修复
agent: go-build-resolver
最小改动、快速绿灯


/go-test
Go 的 TDD/测试套路
workflow
table-driven tests、race、coverage


/python-review
Python 专用审查
agent: python-reviewer
PEP8、类型标注、安全与性能


/refactor-clean
死代码识别与清理
agent: refactor-cleaner（概念上）
强调安全删除 + 验证


/update-docs
文档同步
agent: doc-updater（概念上）
从 source-of-truth 同步


/update-codemaps
生成/更新 codemaps
agent: doc-updater（概念上）
适合大仓库导航


/orchestrate
顺序式多 agent 协作（复杂任务）
workflow
把任务拆阶段推进


/multi-plan
多模型协作产计划
workflow
高级用法，依赖额外 wrapper/MCP


/multi-execute
多模型协作执行与审计
workflow
高级用法，依赖额外 wrapper/MCP


/multi-frontend
偏前端多模型流程
workflow
文档标注“Gemini-led”


/multi-backend
偏后端多模型流程
workflow
文档标注“Codex-led”


/multi-workflow
全流程多模型协作
workflow
该命令文档的 usage 写成 /workflow ...；以文件名映射的命令 /multi-workflow 为准


/pm2
多服务 PM2 初始化与命令生成
workflow
生成 ecosystem.config.cjs 与 .claude/commands/pm2-*.md




8. Agents（子代理，全量拆解）
ECC 的 agents 放在 agents/，每个 agent 都带明确的 “when to use/工具权限/模型选择”。在 Claude Code 中，这些 agent 常被 commands 间接调用。
8.1 Agent 清单（13 个）



Agent
主要职责
默认模型
Tools（声明）
常见入口




planner
复杂需求拆解为可执行计划，并等待确认
opus
Read,Grep,Glob
/plan


architect
架构设计与技术决策（边界、扩展性、风险）
opus
Read,Grep,Glob
（手动委托/复杂方案评审）


tdd-guide
强制 TDD（先测后码、覆盖率目标）
opus
Read,Write,Edit,Bash,Grep
/tdd


code-reviewer
质量 + 安全 + 可维护性审查
opus
Read,Grep,Glob,Bash
/code-review


security-reviewer
安全漏洞检测与修复建议
opus
Read,Write,Edit,Bash,Grep,Glob
（敏感改动后）


build-error-resolver
修 build/TS 错误，最小 diff 快速变绿
opus
Read,Write,Edit,Bash,Grep,Glob
/build-fix


e2e-runner
Playwright E2E（含 flaky 隔离与 artifacts）
opus
Read,Write,Edit,Bash,Grep,Glob
/e2e


refactor-cleaner
死代码识别与清理（分析→验证→删除）
opus
Read,Write,Edit,Bash,Grep,Glob
/refactor-clean


doc-updater
文档/codemap 同步与生成
opus
Read,Write,Edit,Bash,Grep,Glob
/update-docs、/update-codemaps


go-reviewer
Go 代码审查（惯用法/并发/错误处理/性能）
opus
Read,Grep,Glob,Bash
/go-review


go-build-resolver
Go build/vet/lint 修复（最小改动）
opus
Read,Write,Edit,Bash,Grep,Glob
/go-build


python-reviewer
Python 审查（PEP8/类型标注/安全/性能）
opus
Read,Grep,Glob,Bash
/python-review


database-reviewer
PostgreSQL/Supabase（schema/index/query/security/perf）
opus
Read,Write,Edit,Bash,Grep,Glob
（SQL/migration/慢查询时）



planner

职责：复杂功能/重构的计划拆解；输出阶段化计划并等待确认。
常见入口：/plan

architect

职责：系统设计与架构决策（可扩展性、边界划分、风险评估）。

tdd-guide

职责：强制 TDD（先测后码、覆盖率目标）。
常见入口：/tdd

code-reviewer

职责：质量 + 安全的代码审查；仓库强调“写完代码立即用”。
常见入口：/code-review

security-reviewer

职责：安全漏洞检测与修复建议（secrets、注入、SSRF、OWASP Top 10 等）。

build-error-resolver

职责：修 build/TS 错误；强调最小 diff、快速让 build 变绿。

e2e-runner

职责：Playwright E2E（生成/维护/执行）、隔离 flaky tests、收集 artifacts。
常见入口：/e2e

refactor-cleaner

职责：死代码清理与收敛（仓库说明会用 knip/depcheck/ts-prune 等分析）。
常见入口：/refactor-clean

doc-updater

职责：文档与 codemap 同步；生成/更新 docs/CODEMAPS/* 等结构化文档。
常见入口：/update-docs、/update-codemaps

语言/领域专项：

go-reviewer：Go 代码审查（并发、错误处理、性能、惯用法）。
go-build-resolver：Go build/vet/lint 问题修复。
python-reviewer：Python 代码审查（PEP8、类型标注、安全、性能）。
database-reviewer：PostgreSQL/Supabase（schema/index/query/security/perf）。

8.2 “什么时候用哪个 agent”（更可操作的规则）

需求不清/涉及多模块：先 /plan（planner）把边界与风险说清。
你准备“动架构”：先 architect 让它给出候选方案与 trade-off。
新功能/修 bug：直接 /tdd，用测试把需求钉死。
改完代码：立刻 /code-review，把 CRITICAL/HIGH 先压下去。
build 红了：用 build-error-resolver（或 /build-fix）做最小修复闭环。
E2E 缺口：用 e2e-runner 明确用户旅程与断言。
DB/migration/慢查询：拉 database-reviewer，优先看索引/查询计划/事务边界。


9. Hooks（自动化钩子，逐条拆解 + 可复制模板）
ECC 的 hooks 文件是 hooks/hooks.json。核心特点：

全部用 Node.js 实现，跨平台（Windows/macOS/Linux）。
既包含“提醒类”hooks，也包含“阻断类”hooks（会 exit(1) 直接阻止危险操作）。
多个脚本通过 ${CLAUDE_PLUGIN_ROOT} 定位插件根目录（插件安装场景下可用）。

9.1 ECC hooks.json 做了什么（按触发点逐条解释）
PreToolUse（工具执行前）：

Dev server 必须在 tmux：当检测到 npm run dev / pnpm dev / yarn dev / bun dev，且不在 tmux 中时，会直接阻断并提示用 tmux 启动。
长命令 tmux 提醒：对 install/test/cargo/docker/pytest/vitest/playwright 等命令给 tmux 提醒。
git push 提醒：push 前提醒你复查变更（默认不阻断）。
阻止随手创建零散文档：当 Write 创建 .md/.txt 且不是 README/CLAUDE/AGENTS/CONTRIBUTING 时，直接阻断。
strategic compact 提醒：对任意 Edit/Write，调用 scripts/hooks/suggest-compact.js 做“到阈值建议 /compact”。

PreCompact（压缩前）：

保存压缩前状态：调用 scripts/hooks/pre-compact.js。

SessionStart（会话开始）：

会话启动加载上下文并检测包管理器：调用 scripts/hooks/session-start.js。

PostToolUse（工具执行后）：

Bash 里检测 gh pr create：输出 PR URL，并给出 gh pr review 复查命令。
build 后台分析示例：对 build 命令注册了一个 async: true 的示例 hook（不阻塞）。
Edit 后自动 Prettier：编辑 .ts/.tsx/.js/.jsx 后自动 npx prettier --write 。
Edit 后 TypeScript 检查：编辑 .ts/.tsx 后在最近的 tsconfig.json 所在目录执行 npx tsc --noEmit，并只打印涉及该文件的错误行。
Edit 后 console.log 警告：编辑 .ts/.tsx/.js/.jsx 后扫描该文件，发现 console.log 就警告。

Stop（单次响应结束后）：

统一 console.log 审计：调用 scripts/hooks/check-console-log.js（针对 modified files 做审计）。

SessionEnd（会话结束）：

会话结束持久化：调用 scripts/hooks/session-end.js。
会话模式抽取：调用 scripts/hooks/evaluate-session.js（服务于 continuous-learning）。

9.2 最小可用 hooks 模板（插件安装场景，直接可用）
注意：如果你是“按 ECC 插件方式安装”，Claude Code 通常会按插件约定自动加载插件内的 hooks/hooks.json。下面片段主要用于“你想按自己的口味裁剪/重写 hooks”的场景；若你直接复制粘贴导致 hooks 重复执行，请删掉重复项，只保留一份来源。
把下面片段合并到 ~/.claude/settings.json 的 hooks 字段即可（会用到 ${CLAUDE_PLUGIN_ROOT}）：
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "tool == \"Edit\" || tool == \"Write\"",
        "hooks": [
          {
            "type": "command",
            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hooks/suggest-compact.js\""
          }
        ]
      }
    ],
    "PreCompact": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hooks/pre-compact.js\""
          }
        ]
      }
    ],
    "SessionStart": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hooks/session-start.js\""
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hooks/check-console-log.js\""
          }
        ]
      }
    ],
    "SessionEnd": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hooks/session-end.js\""
          }
        ]
      },
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hooks/evaluate-session.js\""
          }
        ]
      }
    ]
  }
}

9.3 语言专项 hooks（可选）
TypeScript/JavaScript（格式化 + 类型检查 + console.log）：
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "tool == \"Edit\" && tool_input.file_path matches \\\"\\\\.(ts|tsx|js|jsx)$\\\"",
        "hooks": [{
          "type": "command",
          "command": "node -e \"const{execFileSync}=require('child_process');const fs=require('fs');let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{const i=JSON.parse(d);const p=i.tool_input?.file_path;if(p&&fs.existsSync(p)){try{execFileSync('npx',['prettier','--write',p],{stdio:['pipe','pipe','pipe']})}catch(e){}}console.log(d)})\""
        }]
      }
    ]
  }
}

Python/Go 的 hooks，ECC 的规则文件分别建议：

Python：black/ruff + mypy/pyright，警告 print
Go：gofmt/goimports + go vet + staticcheck

下面给出“示例模板”（具体命令与参数以你的项目工具链为准）：
Python（black + ruff + pyright，编辑 .py 后触发；示例参考 ECC 的 Prettier hook 写法，用 stdin JSON 取 tool_input.file_path）：
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "tool == \"Edit\" && tool_input.file_path matches \\\"\\\\.py$\\\"",
        "hooks": [
          {
            "type": "command",
            "command": "node -e \"const{execFileSync}=require('child_process');const fs=require('fs');let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{const i=JSON.parse(d);const p=i.tool_input?.file_path;if(p&&fs.existsSync(p)){try{execFileSync('python',['-m','black',p],{stdio:['pipe','pipe','pipe']})}catch(e){}try{execFileSync('python',['-m','ruff','check','--fix',p],{stdio:['pipe','pipe','pipe']})}catch(e){}}try{execFileSync('pyright',['.'],{stdio:['pipe','pipe','pipe']})}catch(e){}console.log(d)})\""
          }
        ]
      }
    ]
  }
}

Go（gofmt/goimports + go vet，编辑 .go 后触发；同样从 stdin JSON 获取文件路径）：
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "tool == \"Edit\" && tool_input.file_path matches \\\"\\\\.go$\\\"",
        "hooks": [
          {
            "type": "command",
            "command": "node -e \"const{execFileSync}=require('child_process');const fs=require('fs');let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{const i=JSON.parse(d);const p=i.tool_input?.file_path;if(p&&fs.existsSync(p)){try{execFileSync('gofmt',['-w',p],{stdio:['pipe','pipe','pipe']})}catch(e){}try{execFileSync('goimports',['-w',p],{stdio:['pipe','pipe','pipe']})}catch(e){}}try{execFileSync('go',['vet','./...'],{stdio:['pipe','pipe','pipe']})}catch(e){}console.log(d)})\""
          }
        ]
      }
    ]
  }
}


10. MCP（mcp-configs/mcp-servers.json，全量拆解）
ECC 给了一个 MCP server 配置样例文件：mcp-configs/mcp-servers.json。
它的定位是：你不要全盘照抄启用，而是把“你当前项目确实需要的那几个”拷贝到 ~/.claude.json 的 mcpServers 里。

作者经验：MCP/插件开太多会显著压缩上下文窗口。建议“配置 20-30 个，但每项目启用 < 10 个、活跃 tools < 80 个”。

10.1 服务器清单（按 ECC 样例）
github

类型：stdio（npx）
env：GITHUB_PERSONAL_ACCESS_TOKEN
用途：PR / issue / repo 操作

firecrawl

类型：stdio（npx）
env：FIRECRAWL_API_KEY
用途：网页抓取/爬取

supabase

类型：stdio（npx）
参数：--project-ref=YOUR_PROJECT_REF
用途：Supabase DB 操作

memory

类型：stdio（npx）
用途：跨会话持久化记忆（注意也会占用上下文与工具额度）

sequential-thinking

类型：stdio（npx）
用途：链式推理辅助

vercel

类型：http（远程）
url：https://mcp.vercel.com
用途：Vercel 部署/项目

railway

类型：stdio（npx）
用途：Railway 部署

Cloudflare（4 个 http MCP）：

cloudflare-docs：https://docs.mcp.cloudflare.com/mcp（文档检索）
cloudflare-workers-builds：https://builds.mcp.cloudflare.com/mcp（Workers builds）
cloudflare-workers-bindings：https://bindings.mcp.cloudflare.com/mcp（Workers bindings）
cloudflare-observability：https://observability.mcp.cloudflare.com/mcp（日志/可观测）

clickhouse

类型：http
url：https://mcp.clickhouse.cloud/mcp
用途：ClickHouse 分析查询

context7

类型：stdio（npx）
用途：实时文档检索（Context7）

magic

类型：stdio（npx）
用途：Magic UI 组件（偏前端）

filesystem

类型：stdio（npx）
参数：@modelcontextprotocol/server-filesystem 后面要填你自己的路径（示例是 /path/to/your/projects）
用途：文件系统操作（风险较高；建议限制授权范围）

10.2 占位符与安全建议

ECC 样例里有大量 YOUR_*_HERE：必须替换成你自己的值，并尽量用环境变量注入。
如果你把 MCP 配置提交到 Git：不要把 token/key 直接写进文件。
若你发现“上下文缩水很快/工具列表很长”：优先禁用不必要的 MCP。


11. 最小启用集（按技术栈给出可落地的“默认方案”）
这里的目标是：不要一上来全开 ECC 的所有功能（尤其是 MCP/插件/钩子），而是按项目栈选择一个“够用且可维护”的最小集合。
11.1 TypeScript / React / Next.js 项目（推荐起步）
Rules（必装）：

rules/common/
rules/typescript/

Skills（推荐）：

skills/coding-standards
skills/tdd-workflow
skills/verification-loop
skills/security-review
skills/backend-patterns（有 API/DB）
skills/frontend-patterns（有复杂 UI）
skills/strategic-compact（会话长时非常实用）
可选：skills/continuous-learning 或 skills/continuous-learning-v2

Commands（推荐日常链路）：

/plan → /tdd → /code-review → /verify pre-pr
有关键用户旅程：加 /e2e

MCP（建议先启用 3-6 个内）：

context7：查文档（省掉大量复制粘贴）
github：PR/issue 操作（如果你真的常用 MCP 而不是 gh CLI）
firecrawl：需要抓网页时再启用
supabase：确实用 Supabase 时才启用
不建议默认启用：filesystem（权限面大）、memory（工具增多会压缩上下文）

Hooks（建议先上“轻量且收益高”的部分）：

strategic compact（提醒你在里程碑节点 /compact）
console.log 审计（Edit 后提醒 + Stop 审计）
Prettier 自动格式化（团队已统一 Prettier 时收益很高；否则先别开，避免与现有格式化策略冲突）

11.2 Python / Django 项目
Rules（必装）：

rules/common/
rules/python/

Skills（推荐）：

skills/python-patterns
skills/python-testing
skills/security-review
Django 项目额外：skills/django-patterns、skills/django-security、skills/django-tdd、skills/django-verification
DB 重：skills/postgres-patterns

Commands（推荐）：

/plan → /tdd（后端逻辑）→ /python-review → /verify

MCP（按需）：

context7（通用）
github（按需）
firecrawl（按需）

Hooks（按需）：

black/ruff（团队若统一格式化）
mypy/pyright（项目若有类型标注约束）

11.3 Go 项目
Rules（必装）：

rules/common/
rules/golang/

Skills（推荐）：

skills/golang-patterns
skills/golang-testing
skills/verification-loop
skills/security-review

Commands（推荐）：

/go-test（TDD/测试）
/go-build（build/vet 修复）
/go-review（审查）

Hooks（推荐）：

gofmt/goimports（确保一致性）
go vet/staticcheck（按项目习惯启用）


12. 常用工作流（把 rules+skills 组合起来用）
12.1 规划 → 实现（TDD）→ 审查 → 验证
/plan "把登录从 session 改成 JWT，并补齐测试"
/tdd
/code-review
/verify

12.2 交付前安全审查
/security
/security-scan


13. OpenCode 支持（可选）
ECC 也提供 OpenCode / Codex 等其他工具的兼容形态；本文这里保留最早整理时的 OpenCode 入口示例：
npm install opencode-ecc

然后在你的 opencode.json 中启用：
{
  "plugin": ["opencode-ecc"]
}

参考：https://raw.githubusercontent.com/affaan-m/everything-claude-code/main/.opencode/README.md

14. 参考链接

仓库主页：https://github.com/affaan-m/everything-claude-code
简体中文 README：https://github.com/affaan-m/everything-claude-code/blob/main/README.zh-CN.md
Rules 安装与结构：https://github.com/affaan-m/everything-claude-code/blob/main/rules/README.md
Shorthand 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




Oh My OpenCode
Mon, 13 Apr 2026 00:00:00 GMT
Oh My OpenCode (OMO) 使用指南
1. OMO 是什么
Github Repo
Oh My OpenCode（OMO）不是独立 IDE，也不是新命令行工具。它是 OpenCode 的增强层：你仍然使用 opencode，但获得一套多代理、多模型、可编排的工程工作流。

补充：仓库/项目名现在已经迁移到 oh-my-openagent，但产品名、npm 包名、很多配置名与命令仍然沿用 oh-my-opencode 兼容层。

核心能力：

用“规划 -> 执行”拆分复杂任务，提升可控性与闭环率。
支持 ulw（ultrawork）冲刺模式，少指挥、多自动。
提供可验证编辑（LINE#ID），降低 stale-line 误改风险。
支持后台并行（检索/调研/实现可并行推进）。
内置 MCP 生态websearch（Exa）- 实时网页检索、context7 - 官方文档检索、grep_app - GitHub 代码搜索。


2. 安装与初始化

注意：安装后仍然使用 opencode 启动，不存在 omo 命令。

2.1 一键安装（推荐）
把下面提示词直接贴给你的 Agent（Claude Code/Cursor/AmpCode 等）：
Install and configure oh-my-opencode by following the instructions here:
https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/refs/heads/dev/docs/guide/installation.md

2.2 手动安装或更新（回退）
bunx oh-my-opencode@latest install
# 或
npx oh-my-opencode@latest install


当前发布包名仍然是 oh-my-opencode。

2.3 初始化项目上下文（项目根目录）
/init-deep

它会按目录层级生成 AGENTS.md，用于在大仓库中提供就近上下文约束。
2.4 安装后验证
opencode --version

并检查 ~/.config/opencode/opencode.json 的 plugin 数组是否包含 oh-my-opencode。
补充：现在更推荐识别/使用的插件条目名是 oh-my-openagent；旧的 oh-my-opencode 仍可加载，但通常会进入兼容路径。
2.5 配置模型
编辑文件xxx/.config/opencode/oh-my-opencode.json
补充：当前兼容层通常同时识别：

oh-my-openagent.json[c]
oh-my-opencode.json[c]


3. 5 分钟快速上手（Happy Path）
3.1 启动与初始化
cd /path/to/your/project
opencode

进入 TUI 后执行：
/init-deep

3.2 选一种执行模式
模式 A：冲刺（ulw）
帮我把这个页面的深色模式适配一下，顺便补齐测试，ulw

模式 B：先规划后执行（Prometheus + Atlas）

按 Tab 进入 Prometheus 访谈式规划
规划确认后执行：

/start-work


注意：复杂任务请写清楚边界与验收条件，否则规划容易发散、执行容易中断。


4. 工作流与指令（速查）
4.1 触发类型

关键词触发：ulw / ultrawork
prompt 触发：@plan
slash 命令：/init-deep、/start-work 等

4.2 常用指令表



命令/触发
类型
用途
最小用法
常见误用




ulw / ultrawork
关键词
自动化冲刺执行
修复 X 并补测，ulw
把它当 slash 命令


@plan
prompt
复杂任务先规划
@plan 重构鉴权模块并保持行为不变
不给边界与验收


/init-deep
slash
新项目接入 OMO
/init-deep
不在仓库根（或子目录）执行


/start-work
slash
按计划执行闭环
/start-work
没有计划就直接执行


/ulw-loop
slash
ultrawork + 循环推进
/ulw-loop "批量修复 lint + type 错误"
用在小任务上导致过度开销


/ralph-loop
slash
长任务持续推进
/ralph-loop "迁移旧接口到新 SDK"
目标不清晰就开循环


/cancel-ralph
slash
停止 ralph 循环
/cancel-ralph
以为会停止所有机制


/stop-continuation
slash
停止 continuation 机制
/stop-continuation
以为会撤销已完成修改


/refactor
slash
结构化重构入口
/refactor src/auth --strategy=safe
把功能新增当重构任务


/handoff
slash
跨会话交接
/handoff
只写一句话，没带上下文



自定义命令
自定义 Slash 命令可从以下位置加载：
.opencode/commands/*.md（项目）
~/.config/opencode/commands/*.md（用户）
.claude/commands/*.md（Claude Code 兼容）
~/.claude/commands/*.md（Claude Code 用户）

5. 配置与文件（你要改哪里）
5.1 常见配置位置

项目级：.opencode/oh-my-opencode.jsonc
用户级：~/.config/opencode/oh-my-opencode.jsonc

另外，OpenCode 自身插件列表在：~/.config/opencode/opencode.json（用于确认 oh-my-opencode 是否被加载）。
补充：迁移期内，下面两组文件名通常都能被识别：

.opencode/oh-my-openagent.jsonc
.opencode/oh-my-opencode.jsonc
~/.config/opencode/oh-my-openagent.jsonc
~/.config/opencode/oh-my-opencode.jsonc

5.2 最小配置示例
{
  "agents": {
    "sisyphus": { "model": "anthropic/claude-opus-4-6" },
    "hephaestus": { "model": "openai/gpt-5.3-codex" }
  },
  "categories": {
    "visual-engineering": { "model": "google/gemini-3-pro" },
    "quick": { "model": "anthropic/claude-haiku-4-5" }
  }
}

字段含义（只记两点即可）：

agents：为具体 Agent 指定模型（编排/执行/检索等角色）。
categories：为任务类别指定默认模型（例如 visual-engineering）。

5.3 关键文件怎么用



路径
谁生成/谁维护
用途
常见误用




AGENTS.md（分层）
/init-deep 生成
给 agent 提供“就近上下文约束”，减少上下文污染
以为它会自动更新业务规则


.opencode/oh-my-opencode.jsonc
你维护（项目级）
团队共享的 OMO 路由/模型覆盖
提交了本地密钥或私密模型名


~/.config/opencode/oh-my-opencode.jsonc
你维护（用户级）
个人偏好覆盖（不影响仓库）
用用户级配置覆盖掉团队约束


~/.config/opencode/opencode.json
OpenCode 维护
OpenCode 全局配置；用于确认插件已加载（oh-my-openagent / oh-my-opencode）
把 OMO 配置写进这里导致难以迁移




6. 模型路由
OMO 的重点是“任务语义路由”，而不是“手动切模型”。常见角色如下：



代理/类别
核心职责




Sisyphus（总控）
默认总编排器：规划、拆解、并行委派子任务并执行闭环（todo 驱动，强并发）。


Hephaestus（执行）
深度自主实现：复杂调试、架构落地、端到端完成任务（“深度模式/工匠”）。


Oracle（分析推理）
架构决策/代码审查/疑难 Debug 咨询：只读分析，给高质量推理建议。


Librarian（资料库）
多仓库/文档/开源实现检索与对比：证据驱动的解释与定位。


Explore（代码库）
快速扫代码库、grep/上下文定位：为主 Agent 提供“快而准”的线索。


Multimodal-Looker（眼睛）
视觉内容专家：分析 PDF / 图片 / 图表 / 截图提取信息（只读）。


Prometheus（需求访谈）
访谈式规划：通过迭代提问产出可执行的详细计划。


Metis（规划）
计划顾问（pre-planning）：挖掘隐藏意图、歧义、潜在失败点。


Momus（挑刺）
计划审稿人：按清晰度/可验证性/完整性标准“挑刺”与校验。


Atlas（团队管理）
todo-list 执行编排：按计划逐项推进、管理 todo 并协调执行（自身不再委派）。


Sisyphus-Junior（临时工）
被 task(category=...) 生成的执行体：模型随 category 自动选择；禁止再次委派，防止无限递归。



默认模型映射（来自 OMO features文档 ，建议先按默认跑通）：



Agent
推荐模型（默认/备选）




Sisyphus
claude-opus-4-6（Fallback：gpt-5.3-codex → deep quality chain）


Hephaestus
gpt-5.3-codex（Fallback：deep quality chain：claude-opus-4-6-thinking → step-3.5-flash → glm-5 → …）


Oracle
gpt-5.3-codex（Fallback：claude-opus-4-6-thinking → claude-sonnet-4-5-thinking → deep quality chain）


Librarian
claude-sonnet-4-5（Fallback：speed chain：claude-haiku-4-5 → gpt-5-mini → … → quality chain）


Explore
claude-haiku-4-5（Fallback：oswe-vscode-prime → gpt-5-mini → gpt-4.1 → extended speed chain）


Multimodal-Looker
gemini-3-pro-image（Fallback：gemini-3-pro-high → gemini-3-flash → kimi-k2.5 → claude-opus-4-6-thinking → claude-sonnet-4-5-thinking → claude-haiku-4-5 → gpt-5-nano）


Prometheus
claude-opus-4-6-thinking（Fallback：gpt-5.3-codex → claude-sonnet-4-5-thinking → deep quality chain）


Metis
claude-opus-4-6-thinking（Fallback：gpt-5.3-codex → claude-sonnet-4-5-thinking → deep quality chain）


Momus
gpt-5.3-codex（Fallback：claude-opus-4-6-thinking → deep quality chain）


Atlas
claude-sonnet-4-5-thinking（Fallback：claude-opus-4-6-thinking → gpt-5.3-codex → deep quality chain）


Sisyphus-Junior
(category-dependent)（随 category 自动选模型）






Category
默认模型
典型用途




visual-engineering
google/gemini-3-pro
前端 / UI/UX / 动效 / 视觉实现


ultrabrain
openai/gpt-5.3-codex（xhigh）
极深推理、复杂架构决策


deep
openai/gpt-5.3-codex（medium）
“深度模式”自主问题解决


artistry
google/gemini-3-pro（max）
创意/审美/新颖方案


quick
anthropic/claude-haiku-4-5
小修小补、低成本快速改动


unspecified-low
anthropic/claude-sonnet-4-6
通用低难任务


unspecified-high
anthropic/claude-opus-4-6（max）
通用高难任务


writing
kimi-for-coding/k2p5
文档、说明、技术写作




7. FAQ（常见坑）
7.1 为什么看不到 OMO 效果？
先确认你是用 opencode 启动，并且插件已加载；再确认是否触发了 ulw 或 /start-work 路径。
7.2 任务经常中途停？
复杂任务先规划再执行，尽量给出明确验收条件，不要只给一句模糊需求。
7.3 我应该先学哪三个？

/init-deep
ulw
/start-work


8. 参考链接
https://github.com/code-yeongyu/oh-my-openagent
https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/refs/heads/dev/docs/guide/installation.md
https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/refs/heads/dev/docs/guide/overview.md
https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/refs/heads/dev/docs/guide/orchestration.md
https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/refs/heads/dev/docs/reference/features.md
https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/refs/heads/dev/docs/reference/configuration.md




Spec Kit（spec-kit）
Mon, 13 Apr 2026 00:00:00 GMT
Spec Kit（spec-kit）使用指南
1. Spec Kit 是什么
Github Repo
Spec Kit 是 GitHub 出品的“Spec Driven Development”工具包：用 specify CLI + 一套 speckit.* 命令模板，把“想法 -> 规格 -> 计划 -> 任务 -> 实现”固化成可重复的工程流程。
核心能力：

一条命令初始化项目内的 .specify/ 工作区与 AI 工具命令集（Claude/Codex/Cursor/Gemini/OpenCode 等）。
用 speckit.* 命令生成 specs// 下的规格、计划与任务拆解。
支持两种脚本模板：--script sh（Bash）与 --script ps（PowerShell）。
提供扩展系统（extensions）：在 .specify/extensions.yml 声明并按需启用额外命令/规则。


补充：当前官方流程已经明确包含 /speckit.implement，并新增 /speckit.clarify、/speckit.analyze、/speckit.checklist 这些增强命令。


2. 安装与部署

Spec Kit 本质是一个 Python CLI（命令为 specify），仓库内文档使用 uv(python pip install uv) 安装/运行。

2.1 macOS / Windows / Linux

README 主要以 uv（跨平台）安装为例。

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git
specify --help

一次性运行（免安装）：
uvx --from git+https://github.com/github/spec-kit.git specify --help

2.2 Docker（可选）
如需容器化，通常做法是在镜像中安装 uv 与 specify-cli，并挂载项目目录运行 specify。

3. 快速上手（Happy Path）
3.1 初始化（项目根目录）
cd /path/to/your/project
specify init

常用参数：
specify init --ai claude
specify init --ai codex
specify init --script sh   # Bash 模板
specify init --script ps   # PowerShell 模板（无需 WSL）


注意：--ai generic 必须同时指定 --ai-commands-dir（命令输出目录），否则会报错并退出。

3.2 生成一个 feature 的规格/计划/任务（以 Claude Code 为例）

/speckit.constitution -> .specify/memory/constitution.md
/speckit.specify -> specs//spec.md
/speckit.clarify（推荐） -> 先补清需求中的歧义项
/speckit.plan -> specs//plan.md + research.md + data-model.md + quickstart.md + contracts/
/speckit.tasks -> specs//tasks.md（注意：tasks.md 不由 /speckit.plan 生成）
/speckit.analyze（可选） -> 在实现前做规格/计划/任务之间的一致性检查
/speckit.implement -> 按计划和任务开始实现


注意： 默认来自当前 git 分支（如 001-photo-albums）；非 git 工作流可设置 SPECIFY_FEATURE。


4. 深度功能（你会真正用到的亮点）
4.1 specify check：环境自检
specify check

它会检查依赖与部分常用工具是否可用，并对 Claude 做额外路径提示（例如 ~/.claude/local/claude）。
4.2 Extensions：把新能力“挂载”到 Spec Kit
specify extension --help

扩展相关目录：.specify/extensions.yml、.specify/extensions/.registry、.specify/extensions/.cache/。

5. Spec 生成文件怎么用（重点）
Spec Kit 的输出以 specs// 为中心。常见顺序：先写规格（spec）再写计划（plan）再拆任务（tasks），最后实现与验收。

注意： 默认来自当前 git 分支名；不走 git 分支流时，先设置 SPECIFY_FEATURE。

5.1 输出清单（每个文件怎么用）



路径
生成来源
你用它做什么（建议亲自审一遍）
下一步




spec.md
/speckit.specify
写清用户故事（含优先级 P1/P2/P3）、验收场景（Given/When/Then）、边界条件（Edge Cases）、需求（FR-xxx）、成功标准（SC-xxx）
把 “NEEDS CLARIFICATION” 清零后再做 plan


plan.md
/speckit.plan
实现路线图：技术上下文、门禁（Constitution Check）、项目结构选择、复杂度偏离说明、分阶段交付与验证点
以它为准做任务拆解


research.md
/speckit.plan
Phase 0：把 spec.md 里的不确定项逐条补齐（尤其是 “NEEDS CLARIFICATION”）
结论要回写到 plan/contracts/data-model


data-model.md
/speckit.plan
Phase 1：把关键实体/字段/关系/约束写成可实现的数据模型
先对齐模型，再写代码与测试


quickstart.md
/speckit.plan
Phase 1：最短验证路径（命令块 + 成功判据），用于 smoke test/交付演示
实现完成后用它做最后验收


contracts/
/speckit.plan
Phase 1：接口契约（例如 OpenAPI/JSON schema/事件定义），用于契约测试与 mock
契约优先更新，再改实现与测试


tasks.md
/speckit.tasks
可执行清单：按 User Story 分组；任务带 ID（T001…）；[P] 可并行；可选 tests（仅 spec 要求时才写）
按任务逐条落地并回填验证结果



典型写法（示意，按你项目改字段即可）：
## Acceptance Scenarios
### SC-001: Anonymous user can sign up
Given ...
When ...
Then ...

- [ ] T001 [P] Implement signup endpoint
Done when: ...

5.2 迭代建议（不容易跑偏的最小闭环）

先把 spec.md 的验收场景写到位（Happy path + 失败路径）。
发现不确定性就让 /speckit.plan 补齐 research.md，把结论转成约束条目。
数据/接口变化先落到 data-model.md 与 contracts/，再改实现。
每次大改 spec 后，重新生成/修订 plan.md 和 tasks.md（避免任务与规格脱节）。


6. 进阶/架构信息（精准速查）
Spec Kit 的数据都落在项目目录中（不使用数据库），路径在 macOS/Windows/Linux 下保持一致（均为项目相对路径）。
6.1 关键目录



位置
用途




.specify/
工作区根目录（memory/templates/scripts/extensions 等）


.specify/memory/constitution.md
项目“宪法”；若已存在，初始化不会覆盖


.specify/templates/
命令模板（例如 constitution-template.md）


.specify/scripts/
内置脚本（按 `--script sh


.specify/extensions.yml
扩展启用清单（YAML）


.specify/extensions/.registry
扩展注册表（已安装/启用状态）


.specify/extensions/.cache/
扩展与 catalog 缓存目录


.specify/extensions//
单个扩展的本地文件与配置


.specify/extensions//-config.yml
扩展项目级配置（可选）


.specify/extensions//local-config.yml
扩展本地配置（可选，通常不入库）




6.2  specify init 参数（以源码为准）



参数
是否必填
说明




--ai 
否
选择 AI 工具模板；不传则交互式选择


`--script sh
ps`
否


--here
否
将模板写入当前目录（而非创建新目录）


--force
否
跳过覆盖/危险操作确认


--no-git
否
不要求/不依赖 git 分支名推导 feature


--github-token 
否
GitHub API Token（用于拉取最新模板 release）


--skip-tls
否
跳过 TLS 校验（仅排障）


--debug
否
打印调试日志


--ai-commands-dir 
条件必填
仅 --ai generic 需要：把命令文件输出到指定目录


--ai-skills
否
将 speckit.* 安装为 Agent Skills（Prompt.MD）；需要同时指定 --ai




6.3 环境变量（含 extensions 规则）



变量
是否必填
用途




GH_TOKEN
否
GitHub API Token（等价替代 --github-token）


GITHUB_TOKEN
否
GitHub API Token（等价替代 --github-token）


SPECIFY_FEATURE
否
覆盖 feature 名推导（脚本/命令会优先用它）


CODEX_HOME
否
使用 Codex CLI 时需指向项目内 .codex/（示例：export CODEX_HOME="$PWD/.codex"）


SPECKIT___
否
扩展配置覆盖：会覆盖扩展 YAML 中对应键（ 会先转为全大写并把 - 替换为 _）



6.4 各 AI 工具命令落盘位置（常用）



--ai 值
命令目录（项目内）




claude
.claude/commands/


codex
.codex/prompts/


cursor-agent
.cursor/commands/


gemini
.gemini/commands/


opencode
.opencode/command/


copilot
.github/agents/


windsurf
.windsurf/workflows/


generic
由 --ai-commands-dir 指定



AI Skills 安装目录（specify init --ai  --ai-skills）：默认在对应 agent 目录下创建 skills/；Codex 使用 .agents/skills/；若 agent 目录不存在则回退到 .agents/skills/。

注意：仓库源码里支持的 --ai 远不止上表（例如 qwen、kilocode、roo、amp、amazonq 等）；需要全量列表时，读 src/specify_cli/__init__.py 的 AGENT_CONFIG。

6.5 自定义生成模板（按项目改写输出结构）
初始化后，模板在 .specify/templates/；常见包括 spec-template.md、plan-template.md、tasks-template.md、constitution-template.md。你想改“生成的文档长什么样”，就改这些模板，再重新运行对应的 /speckit.* 命令生成新版本。

7. FAQ（常见坑）
7.1 我没用 git 分支，specs// 生成到哪？
设置 feature 名再运行命令即可：
export SPECIFY_FEATURE="001-my-feature"

7.2 specify init --script bash 为什么报错？
当前源码只接受 --script sh 或 --script ps。



Homebrew
Mon, 09 Mar 2026 00:00:00 GMT
Homebrew 使用指南
1. 什么是 Homebrew
Homebrew 官网
Homebrew 是 macOS / Linux 上常用的命令行包管理器。在 Linux 上，它更适合扮演“系统包管理器的补充”：

适合装新工具：当发行版仓库版本偏旧时，Homebrew 往往能提供更现代的 CLI / 开发工具。
跨平台一致：同一套 brew 命令可以同时管理 macOS、Linux，甚至 WSL 2 环境。
隔离性较好：默认安装到 /home/linuxbrew/.linuxbrew，尽量减少对系统目录的直接污染。


建议把 Homebrew 理解为 apt / dnf / pacman 的补充，而不是替代品。内核、驱动、system library、桌面核心组件仍优先交给发行版自身管理。


2. 安装与部署
2.1 环境要求
Homebrew 官方对 Linux 的推荐环境大致如下：

Tier 1：支持窗口内的 Ubuntu，或 Homebrew 官方 Docker 镜像。
默认前缀：/home/linuxbrew/.linuxbrew
架构：x86_64 或 ARM64/AArch64
glibc：>= 2.35 最稳；2.13 ~ 2.34 仍可用，但通常会自动补装 Homebrew 自己的 glibc

如果你装在默认前缀之外，很多包会失去 bottle（二进制包）优势，被迫源码编译，速度更慢、问题更多。
2.2 安装依赖
先用系统包管理器装好基础依赖：
# Debian / Ubuntu
sudo apt-get install build-essential procps curl file git

# Fedora
sudo dnf group install development-tools
sudo dnf install procps-ng curl file

# CentOS Stream / RHEL
sudo dnf group install 'Development Tools'
sudo dnf install procps-ng curl file

# Arch Linux
sudo pacman -S base-devel procps-ng curl file git

2.3 一行命令安装
执行官方安装脚本：
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Linux 下推荐安装位置是：
/home/linuxbrew/.linuxbrew

安装过程中可能会请求 sudo 来创建或修复默认前缀；安装完成后，日常 brew install 一般不再需要 sudo。
2.4 配置环境变量
安装完成后，把 brew 加入当前 shell：
test -d ~/.linuxbrew && eval "$(~/.linuxbrew/bin/brew shellenv)"
test -d /home/linuxbrew/.linuxbrew && eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"
echo 'eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"' >> ~/.bashrc

如果你用的是 zsh，把最后一行写入 ~/.zshrc 即可。
2.5 验证安装
brew --version
brew config
brew doctor

其中 brew --version 用来确认命令存在，brew config 用来查看当前前缀和系统信息，brew doctor 用来排查常见环境问题。

3. 快速上手
3.1 常用命令速查



操作
命令
示例




搜索软件
brew search 
brew search python


查看详情
brew info 
brew info node


安装软件
brew install 
brew install wget


查看已装
brew list
brew list


检查更新
brew outdated
brew outdated


更新索引
brew update
brew update


升级软件
brew upgrade
brew upgrade


卸载软件
brew uninstall 
brew uninstall wget


清理缓存/旧版本
brew cleanup
brew cleanup


清理无用依赖
brew autoremove
brew autoremove



3.2 先装几个高频工具
Homebrew 在 Linux 上最适合先装现代 CLI 工具：
brew install wget curl jq ripgrep fd fzf bat eza zoxide neovim

如果你是第一次使用，建议顺手了解两个目录：
brew --prefix
brew --cellar

prefix 是 Homebrew 当前工作前缀，cellar 是公式实际安装目录。
3.3 你应该形成的基本习惯
日常维护通常就是这一套：
brew update
brew outdated
brew upgrade
brew cleanup

Homebrew 会自动做部分清理，但手动执行一次 brew cleanup 仍然是好习惯。

4. 开发环境配置（最佳实践）
4.1 核心编程语言
Python
brew install python
python3 --version
pip3 --version

Node.js
brew install node
node --version
npm --version

Go
brew install go
go version

Java（OpenJDK）
brew install openjdk
java --version

4.2 常见构建工具
brew install cmake pkg-config

如果你经常自己编译项目，这两个包基本是高频常客。
4.3 一条建议
在 Linux 上：

系统编译链（如 gcc、make、基础头文件）优先走发行版仓库
用户态开发工具（如 node、go、python、neovim、fzf）优先考虑 Homebrew

这样更稳，也更容易排查问题。

5. 命令行效率神器（CLI Power Tools）



工具
用途
命令




ripgrep
极速全文搜索
brew install ripgrep


fd
更友好的文件搜索
brew install fd


fzf
模糊查找
brew install fzf


bat
带高亮的 cat 替代品
brew install bat


eza
更现代的 ls
brew install eza


zoxide
智能目录跳转
brew install zoxide


jq
JSON 处理
brew install jq


neovim
现代编辑器
brew install neovim




6. 进阶技巧
6.1 锁定版本，防止被升级
如果某个工具版本很关键，可以 pin 住：
brew pin node
brew unpin node

6.2 用 Brewfile 复刻环境
brew bundle 很适合把你的开发机环境声明化：
brew bundle dump --describe --force
brew bundle
brew bundle check

这会在当前目录生成 Brewfile。以后换机器时，直接在同目录执行 brew bundle 即可恢复常用工具。
6.3 管理后台服务
如果某些公式带 service 定义，可以在 Linux + systemd 环境下这样管理：
brew services list
brew services start mysql
brew services stop mysql

6.4 故障排查
遇到安装失败、链接异常、路径混乱时，优先执行：
brew doctor
brew config
brew info 

如果某个包总是在源码编译，先检查自己是不是偏离了默认前缀。
参考链接

Homebrew 官网
Homebrew 官方安装文档
Homebrew on Linux 官方文档
Homebrew 官方命令手册
Homebrew FAQ




nvm指令大全 (含语法结构)
Mon, 02 Mar 2026 20:18:00 GMT
nvm指令大全 (含语法结构)

nvm是一个常用的bode.js版本控制器




数学skills创造者
Mon, 02 Mar 2026 00:00:00 GMT
数学skills创造者

# AGENTS.md — Skill Authoring Agent

## 你的身份
你是**顶尖的数学领域研究者**，同时**精通 AI 工具链与工程化落地**。你擅长把数学任务（证明、推导、建模、算法、数值实验、符号计算）转化为可复用、可维护的 **AI skills**。  
你熟练使用 **LaTeX / Markdown** 进行严谨表达；掌握基础 **Python** 与 **Shell**，能编写小脚本来支撑 skill 的自动化（解析输入、跑实验、生成图表/表格、检查格式、批处理等）。

你拥有并优先使用官方工具 **`skill-creator`** 来创建、更新、拆分与维护 skills。

---

## 目标
为本仓库持续产出高质量 skills，使其：
- **数学严谨**：定义清晰、假设写全、边界条件明确、推导可复核。
- **可执行**：能在真实任务中稳定工作，输入输出规范，失败可诊断。
- **可维护**：结构清晰、命名一致、文档完备、易扩展。
- **可复用**：模块化设计，避免一次性脚本；尽量抽象出通用部件。
- **可测试**：提供最小可复现样例（MRE）与测试用例覆盖典型/极端输入。

---

## 交付物规范（每个 skill 必须包含）
1. **README/说明**（或同等文档）  
   - 该 skill 解决什么问题（范围与非范围）  
   - 输入格式、输出格式（示例必须完整可复制）  
   - 算法/方法概述（必要时给出数学公式）  
   - 复杂度、数值稳定性、常见陷阱  
2. **核心实现**  
   - 清晰的入口函数/命令  
   - 重要参数可配置，默认值合理  
   - 错误处理明确（不要静默失败）  
3. **用例与测试**  
   - 至少 3 个：典型、边界、反例/异常输入  
4. **工程辅助脚本（如需要）**  
   - Python/Shell 小工具，用于生成数据、验证结果、格式检查等  
5. **元信息**  
   - 版本、作者/维护说明、依赖与运行环境

---

## 写作与表达风格
- 面向“懂基础但不一定是数学专家”的读者：**严谨但可读**。
- 公式用 LaTeX，长推导分段并标注关键等价变形。
- 结论要给出**可检验的判据**（例如：误差界、停止条件、数值 sanity checks）。
- 避免堆砌术语；如必须使用，先给出直观解释再给形式定义。

---

## 数学严谨性要求（必须遵守）
- 每个定理/结论都要写清：**假设、结论、适用范围**。
- 明确区分：符号计算 vs 数值计算；精确等式 vs 近似。
- 对随机算法：说明分布假设、失败概率、随机种子策略。
- 对优化/迭代法：给出收敛条件、停止准则、可能不收敛的情形与回退策略。
- 对线性代数/数值算法：关注病态性、条件数、稳定性（必要时提供替代方案）。

---

## Skill 设计流程（强制流程）
1. **需求澄清**：把问题拆成 I/O、约束、成功标准、失败模式。
2. **方案选择**：列出 1–3 个候选方法，比较优缺点后选型。
3. **接口设计**：先写输入输出 schema + 示例，再写实现。
4. **实现最小闭环**：先做 MRE，能跑通再扩展能力。
5. **加入验证**：数值 sanity checks / 单元测试 / 对照验证（如与已知结果比对）。
6. **文档补全**：最后完善 README、示例、常见错误与 FAQ。

---

## 工具使用原则
- **优先使用 `skill-creator`**：创建/更新/重构 skill 的目录、模板、文档骨架与校验。
- 可用 Python/Shell 写小脚本，但遵循：
  - 简单、可移植、少依赖
  - 输出可机器解析（JSON/TSV/纯文本）
  - 失败时给出明确 exit code 与错误信息
- 若需要生成图表/表格：默认用可复现脚本生成，并在文档中引用生成步骤。

---

## 质量门槛（输出前自检清单）
- [ ] 输入输出示例能直接复制运行或复现
- [ ] 关键数学假设已写全（不靠“默认大家知道”）
- [ ] 对边界情况有处理或明确拒绝策略
- [ ] 至少 3 个测试用例通过
- [ ] 文档解释与实现一致（不出现“文档说 A，实现做 B”）
- [ ] 命名、目录、风格与仓库约定一致

---

## 默认目录约定（可按项目实际调整）
- `skills//`
  - `README.md`
  - `skill.md`（或主说明文档）
  - `src/`（实现）
  - `tests/`（测试与样例）
  - `scripts/`（可选：辅助脚本）

---

## 交互原则
- 当信息不足时，先给出**合理默认假设**并标注；同时提供可选分支（不同假设下的实现差异）。
- 如果任务过大：先交付一个可用的 MVP skill，再列出扩展路线图。
- 不输出“空泛建议”，每次都要给出可落地的接口与样例。

## 交互与需求澄清（强制执行）

你在开始写/改任何 skill 之前，**必须先与我对话把需求问清楚**。  
除非我明确说“直接做，不用问了/按你理解先做 MVP”，否则不得跳过澄清阶段。

### 1) 必问清单（不清楚就必须追问）
对每个新 skill/改动请求，至少确认以下要点；任何一项不明确都要继续提问：
- **目标任务**：要解决什么问题？成功标准是什么？
- **输入**：输入数据是什么（格式、范围、单位、精度、是否随机）？有没有示例？
- **输出**：期望输出什么（格式、指标、误差容忍度、证明/数值/图表/代码）？有没有示例？
- **适用范围与非范围**：哪些情况必须支持？哪些可以明确不支持？
- **约束**：性能/复杂度、依赖限制、运行环境（OS/CPU/GPU）、是否离线、是否可联网。
- **数学假设**：需要哪些假设（连续/可微/凸性/独立同分布等）？是否允许近似？
- **验收与测试**：怎么验证正确？需要哪些测试用例（典型/边界/反例）？
- **集成方式**：这个 skill 如何被调用（CLI/函数/工具接口）？目录与命名约定是什么？

### 2) 追问原则（硬规则）
- 只要存在“我可能理解错 >10%”的点，就必须追问。
- 遇到多解/多方案时，必须把分歧点说清，并用问题把我带到可决策状态。
- 不能用模糊词结束（如“应该可以”“大概”）；要么确认，要么追问，要么给出可选项让我选。

### 3) 先问再做的输出格式（推荐）
在澄清阶段，你的回复应按如下结构组织：
1. **我当前理解**：用 3–6 条 bullet 总结你理解的需求（标注你做的假设）。
2. **必须确认的问题（P0）**：不回答就无法动工的关键问题。
3. **最好确认的问题（P1）**：回答后能显著提升质量/减少返工的问题。
4. **你给出的最优建议**：在信息不全的前提下，你认为的最佳默认选择/方案，并解释权衡（可给 1–3 个备选方案）。
5. **下一步**：告诉我只要回答哪些问题，你就能开始产出 MVP。

### 4) 最优建议（必须提供）
即使我没问，你也要在澄清阶段给出你的**最优建议**，包括：
- 推荐的算法/方法路径（含适用条件与风险）
- 推荐的接口与 I/O schema
- 推荐的测试策略与验收标准
- 推荐的工程实现细节（脚本/依赖/目录结构）

### 5) 默认行为（当我没说清时）
- 你可以提出一个**MVP 方案**作为默认建议，但仍需先问清 P0 问题。
- 若我允许“先做 MVP”，你应明确写出：哪些假设是暂定的、哪些点需要我后续确认。





github文档专家
Mon, 02 Mar 2026 00:00:00 GMT
github文档专家

Role
你是一位**基于事实**的开源软件技术文档专家（偏“快速上手 + 深度速查”双模式）。你的任务是：用可核验的仓库证据写出一篇“简约但信息密度极高”的权威使用指南。

Core Protocol（严禁违反）
1) 真实性优先（Zero Hallucination）
- 任何安装命令、参数名、配置文件路径、默认值、环境变量、端口、目录结构：必须来自仓库真实内容（README/docs/wiki/源码/CLI --help）。
- 不确定就写“未在仓库中找到/无法确认”，并指出你查过哪些文件/位置。

2) MCP 强制调用（必须执行，否则停止）
- 必须使用 `mcp context7` 、 `mcp chrome` 或 `web_fetch` 打开 GitHub 仓库主页。
- 必须阅读：`README.md` + 官方 docs（`/docs`、`/doc`、`/wiki`、`/examples`、`/docker*`、`/compose*` 等）。
- 若当前执行环境缺少 MCP：必须明确声明“无法按协议验证”，并停止输出（不要凭经验补全）。

3) 源码级验证（README 不完整时必须做）
- 目标：把“隐藏配置/环境变量/默认值/路径推导逻辑”挖出来并写进文档。
- Search Strategy（至少做一次 repo 内搜索）：
  关键词建议：`config` `env` `dotenv` `os.environ` `getenv` `process.env` `Path` `XDG` `APPDATA`
  `default` `default_value` `flags` `argparse` `click` `cobra` `clap` `commander`
  `~/.config` `Library/Application Support` `AppData` `ProgramData`
- 查到的关键结论要能落到具体文件路径（必要时包含函数名/常量名）。

Audience（同时满足）
- Beginner：按 1/2/3 步能跑起来，且知道如何验证“我成功了”。
- Expert：能快速查到“所有指令/子命令/关键参数”“生成/产物文件各自用途”“配置路径/环境变量/数据存储/扩展机制”。

Style Guidelines
- 极简主义：拒绝废话，每段都要能指导行动或提供速查信息。
- 通用兼容：只用标准 Markdown（禁用 VitePress/HTML 特有标签）。
- 代码优先：命令尽量用代码块；信息尽量表格化；示例尽量可复制。
- 防坑提示：用引用块 `> 注意：...`，且必须基于源码或官方文档证据。

Output（只输出 1 个 Markdown 文档）
Frontmatter：
- `title`（项目名）
- `order`（数字）
- `date`（可选）

结构模板（按“前快后细”的风格固定顺序）
1. 项目是什么
- 一句话定义 + GitHub Repo 链接
- 3-4 个核心能力（bullet）

2. 安装与部署（只写仓库证据支持的方式）
- macOS / Windows / Linux（分别给命令）
- Docker（如仓库提供）：给 `docker run` 或 `docker compose`，并提供**环境变量表**（必填/默认值/来源文件）
> 注意：如果仓库没提供 Docker，明确写“未提供官方 Docker 方案”，不要自行编造镜像名。

3. 5 分钟快速上手（Happy Path）
- Step 1 安装 -> Step 2 初始化/配置 -> Step 3 启动 -> Step 4 验证成功（写清“成功判据/预期输出/访问地址”）
- 最少步骤能跑通即可（别展开解释）

4. 防坑提示（只写高频且可证据化的坑）
- 例如：必须先生成某文件、某参数只能取固定值、路径必须存在、BaseURL 是否需要 `/v1` 等

5. 指令与参数速查（专家区开始）
- 列出 CLI 命令树：主命令 + 子命令（来源：`--help` 输出或源码）
- 表格：`命令` / `用途` / `关键参数` / `最小示例` / `验证方法`

6. 文件与目录（重点：生成文件怎么用）
- 以“产物目录”为中心写清楚每个文件/目录：
  `路径` / `谁生成（哪个命令/脚本）` / `它解决什么问题` / `你应该编辑哪里` / `何时需要重新生成` / `常见误用`
- 如果项目是“生成式工作流”（spec/plan/tasks 等），必须明确“推荐顺序”和“闭环验收点”。

7. 配置、环境变量、默认值（必须精准）
- 配置文件路径表（按 OS；如果项目只用项目内相对路径，也要明确说明）
- 环境变量表：`变量名` / `必填` / `默认值` / `作用` / `从哪读取（源码文件/函数）`

8. 数据存储与运行时行为（如适用）
- 数据落盘位置、格式（SQLite/JSON/LevelDB/纯文件夹）
- 日志位置、端口、缓存目录（以仓库证据为准）

9. FAQ（可选）
- 仅保留“仓库用户最可能遇到且能被事实回答”的问题

验收清单（你写完必须自检）
- 文档里出现的每个命令/参数名：仓库能找到证据（README/docs/源码/--help）。
- 每个路径/环境变量/默认值：能追溯到源码常量或解析逻辑。
- 任何“推测性句子”都被删除或改成“未在仓库中找到”。





PowerShell
Sun, 01 Mar 2026 00:00:00 GMT
PowerShell 使用指南
PowerShell github repo
1. 什么是 PowerShell
PowerShell 是微软官方跨平台任务自动化 Shell，Windows 11 内置 Windows PowerShell 5.1，推荐额外安装更新的 PowerShell 7（pwsh）。
PowerShell 分两条线：

Windows PowerShell 5.1：内置于 Windows，路径 C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe，不再更新。
PowerShell 7（pwsh）：开源跨平台，持续更新，推荐日常使用。两者可共存。

2. 安装 PowerShell 7
方法一：使用 MSI 安装包（推荐）
打开 PowerShell 官方 GitHub 发布页PowerShell github repo release，找到最新版本，下载适用于 Windows 的 .msi 安装包，默认路径安装即可
安装完成后，搜索 "PowerShell 7" 打开即可（不会覆盖 Windows PowerShell）
方法二：通过 Winget 安装（推荐）：
winget install --id Microsoft.PowerShell --source winget

安装后可直接执行 pwsh 启动。
验证版本
pwsh --version
$PSVersionTable

3. 以管理员身份运行

快捷键：Win+R 输入 powershell 或 pwsh，按 Ctrl+Shift+Enter 以管理员身份运行。
右键菜单：在开始菜单找到 PowerShell，右键 → "以管理员身份运行"。
从已有窗口提权：

Start-Process pwsh -Verb RunAs

4. 执行策略（ExecutionPolicy）
默认策略可能阻止运行脚本。查看当前策略：
Get-ExecutionPolicy -List

允许本地脚本运行（推荐开发环境）：
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser




策略
含义




Restricted
不允许运行任何脚本（默认）


RemoteSigned
本地脚本可运行；网络下载的脚本需签名


Unrestricted
允许所有脚本（不推荐）


Bypass
完全绕过，常用于 CI/自动化



5. Profile 配置文件
Profile 是 PowerShell 启动时自动执行的脚本，类似 .bashrc。
查看 Profile 路径：
$PROFILE
$PROFILE | Select-Object *

创建并编辑 Profile（若不存在会新建）：
if (!(Test-Path $PROFILE)) { New-Item -Path $PROFILE -ItemType File -Force }
notepad $PROFILE

常见用途：设置别名、加载模块、自定义提示符（如 oh-my-posh）。
6. 常用命令速查



目的
命令




列出文件
Get-ChildItem（别名 ls/dir/gci）


查看内容
Get-Content （别名 cat）


复制
Copy-Item  


移动/重命名
Move-Item  


删除
Remove-Item 


查看进程
Get-Process


停止进程
Stop-Process -Name 


查看服务
Get-Service


查看环境变量
$env:PATH；Get-ChildItem Env:


查找命令
Get-Command 


查看帮助
Get-Help  -Full


历史记录
Get-History；Ctrl+R 搜索


测试网络连通性
Test-Connection （类似 ping）


DNS 解析
Resolve-DnsName 


查看网络接口
Get-NetIPAddress



7. 管道与对象
PowerShell 传递的是对象而非纯文本，这与 Bash 不同：
# 获取占用内存最多的前5个进程
Get-Process | Sort-Object WorkingSet -Descending | Select-Object -First 5 Name, WorkingSet

# 过滤正在运行的服务
Get-Service | Where-Object Status -eq 'Running'

# 导出为 CSV
Get-Process | Export-Csv processes.csv -NoTypeInformation

8. 模块管理
# 搜索模块
Find-Module 

# 安装模块
Install-Module -Name  -Scope CurrentUser

# 查看已安装模块
Get-InstalledModule

# 更新模块
Update-Module -Name 

# 导入模块
Import-Module 

常用模块推荐：



模块
用途




PSReadLine
命令行编辑增强（Windows PowerShell 5.1 已内置）


posh-git
Git 状态提示


Terminal-Icons
终端文件图标


Microsoft.WinGet.Client
PowerShell 内操作 WinGet




注：oh-my-posh 已从 PowerShell 模块迁移为独立可执行程序，推荐通过 winget install JanDeDobbeleer.OhMyPosh 安装，不再使用 Install-Module oh-my-posh。

9. 实用技巧
# 测量命令耗时
Measure-Command { Get-ChildItem -Recurse }

# 将输出同时显示并写入文件
Get-Process | Tee-Object -FilePath processes.txt

# 后台运行任务
$job = Start-Job { ping 8.8.8.8 -n 4 }
Receive-Job $job -Wait

# 字符串格式化
"Hello, {0}! Today is {1}" -f "World", (Get-Date -Format "yyyy-MM-dd")

# 快速打开当前目录资源管理器
explorer .

# 重新加载 Profile（不重启终端）
. $PROFILE

10. 与 Windows Terminal 配合
推荐搭配 Windows Terminal 使用 PowerShell 7，可在设置中将 pwsh 设为默认配置文件。
参考：Windows Terminal 文档

参考链接

PowerShell 官方文档
PowerShell GitHub 仓库




WSL
Sun, 01 Mar 2026 00:00:00 GMT
WSL 使用指南
WSL github repo
1. 什么是 WSL
WSL（Windows Subsystem for Linux）是微软官方提供的兼容层，让你在 Windows 上直接运行完整的 GNU/Linux 环境——无需虚拟机，无需双系统。

原生集成：可在 Windows 文件系统与 Linux 互相访问，共享网络。
低开销：WSL 2 基于轻量级 Hyper-V VM，启动快、内存占用低。
开发首选：与 VS Code Remote、Docker Desktop 深度集成，是 Windows 开发者的最佳伴侣。


2. 安装
2.1 一行命令安装（推荐）
以管理员身份打开 PowerShell 或 Windows Terminal，执行：
wsl --install

此命令会自动完成：启用必要的 Windows 功能、安装 WSL 2 内核、安装默认发行版（Ubuntu）。安装完成后需重启。

系统要求：Windows 10 版本 2004（Build 19041）及以上，或 Windows 11。

2.2 安装指定发行版
# 查看可用发行版列表
wsl --list --online

# 安装指定发行版（如 Debian、Kali）
wsl --install -d Debian
wsl --install -d kali-linux

2.3 验证安装
wsl --version
wsl --status
wsl -l -v        # 列出已安装发行版及 WSL 版本


3. 常用命令速查



目的
命令




启动默认发行版
wsl


启动指定发行版
wsl -d 


查看已安装发行版
wsl -l -v


设置默认发行版
wsl --set-default 


停止指定发行版
wsl --terminate 


停止所有发行版
wsl --shutdown


更新 WSL 内核
wsl --update


导出发行版备份
wsl --export  


导入发行版
wsl --import   


卸载发行版
wsl --unregister 




4. 文件系统互操作
4.1 从 Windows 访问 Linux 文件
在资源管理器地址栏输入 \\wsl$ 或 \\wsl.localhost，可浏览所有发行版的文件系统。
Linux 文件路径映射示例：
\\wsl.localhost\Ubuntu\home\username\project

4.2 从 Linux 访问 Windows 文件
Windows 的各盘符挂载在 /mnt/ 下：
ls /mnt/c/Users
cd /mnt/d/Projects

4.3 互调命令
# 在 PowerShell 中执行 Linux 命令
wsl ls -la /home

# 混合管道
wsl ls -la | findstr ".md"
dir | wsl grep ".md"

# 在 WSL 中调用 Windows 程序
notepad.exe .bashrc
explorer.exe .        # 用资源管理器打开当前目录
code .                # 用 VS Code 打开


性能提示：将项目文件放在 Linux 文件系统（~/projects）内，而非 /mnt/c/，可获得显著更好的 IO 性能。


5. 配置文件
WSL 有两个配置文件，分别作用于不同范围：
5.1 .wslconfig（全局，WSL 2 VM 设置）
位于 %UserProfile%\.wslconfig（即 C:\Users\<你的用户名>\.wslconfig），控制 WSL 2 虚拟机资源。
# 全局 WSL 2 虚拟机设置
[wsl2]
# 限制内存（默认为物理内存的 50%）
memory=4GB

# 分配虚拟 CPU 数量
processors=4

# 交换空间（默认为 RAM 的 25%）
swap=2GB

# 启用镜像网络（Windows 11 22H2+，让 WSL 与 Windows 共享同一 IP）
# networkingMode=mirrored

[experimental]
# 稀疏 VHD，按需分配磁盘，节省空间
sparseVhd=true

修改后执行 wsl --shutdown 再重启生效。
5.2 wsl.conf（per-distro，发行版内部设置）
在 Linux 发行版内编辑 /etc/wsl.conf，控制该发行版的行为。
[boot]
# 启用 systemd（Ubuntu 22.04+ / Debian 推荐开启）
systemd=true

[automount]
# 自动挂载 Windows 盘符
enabled=true
options="metadata,uid=1000,gid=1000,umask=022"

[network]
hostname=my-wsl
generateResolvConf=true

[interop]
# 允许从 WSL 调用 Windows 程序
enabled=true
appendWindowsPath=true


6. 开发环境最佳实践
6.1 与 VS Code 集成
安装 VS Code 扩展 Remote - WSL（或 Remote Development 包），然后在 WSL 终端中：
code .

VS Code 将在 WSL 内运行服务器，完全原生 Linux 开发体验。
6.2 与 Docker Desktop 集成
Docker Desktop 支持 WSL 2 后端。在 Docker Desktop 设置中启用 Use the WSL 2 based engine，并在 Resources → WSL Integration 中勾选目标发行版。之后在 WSL 内即可直接使用 docker 命令。
6.3 Git 凭据共享
让 WSL 内的 Git 使用 Windows 的凭据管理器，避免重复登录：
git config --global credential.helper "/mnt/c/Program\ Files/Git/mingw64/bin/git-credential-manager.exe"


7. 故障排查
# 查看 WSL 版本与内核信息
wsl --version

# 更新 WSL 内核
wsl --update

# 强制重置 WSL 2 内核（修复异常）
wsl --update --rollback

# 重启所有 WSL 实例
wsl --shutdown

常见问题：



现象
原因 / 解决




wsl --install 报错 0x800701bc
WSL 内核未更新，运行 wsl --update


发行版启动后立即退出
尝试 wsl --shutdown 再重启；或检查 wsl.conf 语法


访问 /mnt/c 性能慢
将项目迁移到 Linux 文件系统内（~/）


网络无法访问
执行 wsl --shutdown 重启；或检查 .wslconfig 网络设置




参考链接

WSL 官方文档
WSL GitHub 仓库
WSL 配置参考（.wslconfig & wsl.conf）




git指令大全 (含语法结构)
Thu, 26 Feb 2026 23:27:00 GMT
git指令大全 (含语法结构)

git是一个常用的版本控制器


注：本页按「高频速查 + 分类指令全集」组织；部分命令（如 reset --hard、push :branch、branch -D）具有破坏性，请谨慎使用。

1. 常用 Git 指令 (高频精简版)



指令
语法结构
描述




git init
git init
初始化本地仓库


git clone
git clone <仓库地址>
克隆远程仓库


git status
git status
查看工作区与暂存区状态


git add
git add <文件> 或 git add .
添加变更到暂存区


git commit
git commit -m '<说明>'
提交暂存区到本地仓库


git log
git log --oneline --graph
查看提交历史


git diff
git diff / git diff --cached
查看未暂存/已暂存差异


git branch
git branch / git branch -a
查看分支


git switch
git switch <分支>
切换分支


git merge
git merge <分支>
合并分支


git fetch
git fetch --prune
拉取远程更新（不自动合并）


git pull
git pull <远程> <分支>
拉取并合并


git push
git push <远程> <分支>
推送本地提交到远程


git stash
git stash / git stash pop
临时保存并恢复工作区修改




2. Git 指令全集 (分类速查)
2.1 仓库初始化与配置



指令
语法结构
描述




git init
git init
初始化仓库


git clone
git clone <仓库地址>
克隆远程仓库


git config
git config --global user.name '<用户名>'
配置全局用户名


git config
git config --global user.email '<邮箱>'
配置全局邮箱


git config
git config --global color.ui true
启用命令输出着色


git config
git config --global --unset http.proxy
取消 Git 代理


git remote
git remote add origin <仓库地址>
添加远程仓库别名


git remote
git remote -v
查看远程仓库地址



2.2 工作区与提交



指令
语法结构
描述




git status
git status
查看当前状态


git add
git add <文件>
暂存指定文件


git add
git add .
暂存当前目录全部变更


git commit
git commit -m '<说明>'
创建提交


git commit
git commit -am '<说明>'
跳过 add 提交已跟踪文件


git commit
git commit --amend -m '<说明>'
修改最近一次提交


git rm
git rm <文件>
删除文件并记录到暂存区


git mv
git mv <旧名> <新名>
重命名并记录变更


git ls-files
git ls-files
查看索引中已跟踪文件



2.3 日志与差异分析



指令
语法结构
描述




git log
git log
查看完整提交日志


git log
git log -n <数量>
查看最近 N 条日志


git log
git log --stat
查看日志及文件统计


git log
git log -p -m
查看日志及补丁内容


git log
git log --pretty=format:'%h %s' --graph
图形化简洁日志


git show
git show 
查看指定提交详情


git show
git show HEAD / git show HEAD^
查看当前/父提交


git diff
git diff
工作区与暂存区差异


git diff
git diff --cached
暂存区与最近提交差异


git diff
git diff HEAD^
与上一个提交比较


git diff
git diff HEAD -- <路径>
与当前提交比较指定路径


git diff
git diff <远程>/<分支>..<本地分支> --stat
对比分支差异统计


git grep
git grep '<模式>'
在版本库中搜索文本



2.4 分支与合并



指令
语法结构
描述




git branch
git branch
查看本地分支


git branch
git branch -a / git branch -r
查看全部/远程分支


git branch
git branch --merged
查看已合并分支


git branch
git branch --no-merged
查看未合并分支


git branch
git branch --contains 
查找包含指定提交的分支


git branch
git branch -m <旧分支> <新分支>
重命名分支


git branch
git branch -d <分支>
删除已合并分支


git branch
git branch -D <分支>
强制删除分支


git checkout
git checkout -b <新分支>
基于当前提交新建并切换


git checkout
git checkout -b <本地分支> <远程>/<分支>
基于远程分支创建本地分支


git checkout
git checkout --track <远程分支>
创建跟踪分支


git switch
git switch <分支>
切换到已有分支


git merge
git merge <分支>
合并指定分支到当前分支


git cherry-pick
git cherry-pick 
摘取单个提交


git rebase
git rebase <目标分支>
变基整理提交历史



2.5 远程同步与发布



指令
语法结构
描述




git fetch
git fetch
获取远程更新


git fetch
git fetch --prune
获取更新并清理远程已删分支


git pull
git pull <远程> <分支>
拉取并合并到当前分支


git push
git push <远程> <分支>
推送当前分支


git push
git push --tags
推送全部标签


git push
git push <远程> :<分支>
删除远程分支



2.6 标签与暂存



指令
语法结构
描述




git tag
git tag
查看标签


git tag
git tag -a <标签> -m '<说明>'
创建附注标签


git show
git show <标签>
查看标签详情


git log
git log <标签>
查看标签对应历史


git stash
git stash
暂存当前修改


git stash
git stash list
查看暂存列表


git stash
git stash show -p stash@{<序号>}
查看某次暂存详情


git stash
git stash apply stash@{<序号>}
应用某次暂存


git stash
git stash pop
应用并删除最近暂存



2.7 回退、恢复与底层排错



指令
语法结构
描述




git checkout
git checkout -- <文件>
丢弃工作区指定文件修改


git reset
git reset --hard HEAD
强制重置到当前提交


git revert
git revert 
反向提交以撤销历史改动


git reflog
git reflog
查看引用变动历史（含丢失提交）


git show
git show HEAD@{}
查看 reflog 指定位置


git show
git show <分支>@{yesterday}
查看分支历史时点状态


git show
git show HEAD~
查看第 n 个祖先提交


git show-branch
git show-branch --all
图示所有分支历史


git whatchanged
git whatchanged
查看提交对应文件变更


git ls-tree
git ls-tree HEAD
查看树对象内容


git rev-parse
git rev-parse 
解析引用对应的 SHA


git gc
git gc
压缩清理仓库对象


git fsck
git fsck
校验仓库对象完整性






Winget
Wed, 11 Feb 2026 00:00:00 GMT
Winget 使用指南
Winget github repo
1. 什么是 Winget
winget（Windows Package Manager CLI）是微软官方包管理器，用于发现、安装、升级、卸载软件。

系统集成：随 App Installer 分发更新（Windows 10 1809+ / Windows 11 / Windows Server 2025）。
覆盖面广：对 MSI/EXE/MSIX 等安装器生态友好，GUI 软件尤其方便。
可复刻环境：export/import 一键恢复常用软件。

2. 安装与验证
Windows 10/11 通常已自带（来自 Microsoft Store 的 App Installer）。若缺失/过旧：在 Microsoft Store 安装或更新 App Installer。
首次登录新系统时 winget 可能延迟出现，可在 PowerShell 触发注册：
Add-AppxPackage -RegisterByFamilyName -MainPackage Microsoft.DesktopAppInstaller_8wekyb3d8bbwe

winget --version
winget --info
winget source list

3. 常用命令



目的
命令




搜索
winget search （可用 --id/--name/--tag/--command 过滤）


详情
winget show --id 


安装
winget install --id  -e（推荐：--id + -e）


已装
winget list


可升级
winget upgrade


全量升级
winget upgrade --all（可加 --include-unknown/--include-pinned）


卸载
winget uninstall --id  -e


迁移
winget export / winget import


Source
winget source list/update


锁版本
winget pin add/list/remove



常用写法（减少交互提示、避免歧义）：
winget install --id Git.Git -e --accept-package-agreements --accept-source-agreements
winget install --id Microsoft.VisualStudioCode -e --accept-package-agreements --accept-source-agreements
winget upgrade --all --accept-package-agreements --accept-source-agreements

常用参数（是否生效取决于安装器/清单）：-s, --source winget|msstore、-h, --silent、-i, --interactive、-v, --version、--scope user|machine、--override/--custom、-l, --location。
4. 迁移与复刻环境：export / import
winget export -o winget-packages.json
winget export -o winget-packages.json --include-versions
winget import -i winget-packages.json --accept-package-agreements --accept-source-agreements

导入常用选项：--ignore-unavailable（有的包找不到也继续）、--ignore-versions（忽略版本装最新版）、--no-upgrade（已装则不升级）。
5. Source 与字体仓库
默认 Source 通常包含 winget（社区）、msstore（商店）、winget-font（字体）。其中 winget-font 常为 Explicit=true，需要显式指定 -s winget-font 才参与搜索/安装。
winget source list
winget source update

6. Pin（锁版本/阻止升级）
pin 用于限制 WinGet 升级行为：pinning（不参与 upgrade --all）、blocking（禁止升级）、gating（允许的版本范围，如 1.2.*）。
winget pin add --id Microsoft.PowerToys -e
winget pin add --id Microsoft.PowerToys -e --blocking
winget pin add --id Microsoft.PowerToys -e --version 0.70.*
winget pin list

7. 故障排查（日志/修复/常见限制）
winget --info
winget list --open-logs
winget install  --verbose-logs

若 winget 本身异常，可用 PowerShell 模块修复：
Install-Module -Name Microsoft.WinGet.Client -Force -Repository PSGallery
Repair-WinGetPackageManager -Force -Latest

常见现象：厂商可能限制 winget 下载 UA 导致 403；winget CLI 不支持 system context。
8. Winget vs Scoop：怎么选
结合 docs/knowledge/sharing/Windows/软件推荐/Scoop.md：GUI/桌面软件优先 winget；CLI/开发工具链与“用户目录不污染”优先 scoop；常见最佳组合是两者并用。
参考链接

Winget GitHub 仓库
Winget 官方文档




OpenSSH
Thu, 05 Feb 2026 00:00:00 GMT
OpenSSH Server (Windows 11 + EasyTier)
作用：在 Windows 11 上启用 OpenSSH Server，可以从其它客户端通过SSH连接到 windows 11 cli，且只监听内网 IP+密钥登录，内网穿透IP可以用Easytier解决。。
1. 前置：确认 EasyTier 主机 IP
ListenAddress 必须提前知道主机 IP（例如 10.144.51.4），不能填网段（例如 10.144.51.0）。
管理员 PowerShell：Win+R 输入 powershell，按 Ctrl+Shift+Enter。
Get-NetIPConfiguration | Format-Table InterfaceAlias,IPv4Address

或：
ipconfig


2. 安装并启用 OpenSSH Server
管理员 PowerShell：
Get-WindowsCapability -Online | Where-Object Name -like 'OpenSSH.Server*'
Add-WindowsCapability -Online -Name OpenSSH.Server~~~~0.0.1.0

启动并设为开机自启：
Start-Service sshd
Set-Service -Name sshd -StartupType Automatic
Get-Service sshd

若不想开机自启：
Set-Service -Name sshd -StartupType Manual

以后每次用Start-Service sshd这个命令手动启动。
（可选）SSH默认 Shell 改为 PowerShell：
New-ItemProperty -Path "HKLM:\SOFTWARE\OpenSSH" -Name DefaultShell `
  -Value "C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe" `
  -PropertyType String -Force


3. 配置 sshd：只允许通过 EasyTier 内网访问
配置文件：C:\ProgramData\ssh\sshd_config
管理员 PowerShell 打开：
notepad C:\ProgramData\ssh\sshd_config

最小可用配置（按需替换端口与 IP）：
Port 22
AddressFamily inet

# 只监听 EasyTier 主机 IP
ListenAddress 10.144.51.4

PubkeyAuthentication yes
AuthorizedKeysFile .ssh/authorized_keys

# 仅用于过渡排错：若你只有 PIN，没有 Windows 密码，这里最终应设为 no
PasswordAuthentication yes

Subsystem sftp sftp-server.exe

应用配置：
Restart-Service sshd


4. 验证监听是否正确
netstat -ano | findstr ":22"

期望看到：10.144.51.4:22 LISTENING
不应看到：0.0.0.0:22 或 [::]:22

5. 密钥登录
5.1 客户端生成密钥
Termux / Linux / macOS / WSL：
ssh-keygen -t ed25519
cat ~/.ssh/id_ed25519.pub

Windows PowerShell：
ssh-keygen -t ed25519
type $env:USERPROFILE\.ssh\id_ed25519.pub

复制整行公钥（以 ssh-ed25519 开头）。

6. 将公钥放到 Windows
6.1 普通用户
路径：C:\Users\<用户名>\.ssh\authorized_keys
示例（用户 USER）：
mkdir C:\Users\USER\.ssh -Force
notepad C:\Users\USER\.ssh\authorized_keys

6.2 用户属于 Administrators 组（关键）
Windows OpenSSH 对管理员组默认使用：C:\ProgramData\ssh\administrators_authorized_keys
检查：
whoami
net localgroup administrators

写入：
notepad C:\ProgramData\ssh\administrators_authorized_keys


7. 修复 Windows 权限（必做）
普通用户（替换用户名与路径）：
icacls C:\Users\USER\.ssh /inheritance:r
icacls C:\Users\USER\.ssh /grant "USER:(F)"
icacls C:\Users\USER\.ssh /grant "SYSTEM:(F)"

icacls C:\Users\USER\.ssh\authorized_keys /inheritance:r
icacls C:\Users\USER\.ssh\authorized_keys /grant "USER:(R)"
icacls C:\Users\USER\.ssh\authorized_keys /grant "SYSTEM:(F)"

管理员组：
icacls C:\ProgramData\ssh\administrators_authorized_keys /inheritance:r
icacls C:\ProgramData\ssh\administrators_authorized_keys /grant "Administrators:(R)"
icacls C:\ProgramData\ssh\administrators_authorized_keys /grant "SYSTEM:(F)"

应用权限：
Restart-Service sshd


8. 客户端连接
ssh -p 22 USER@10.144.51.4

调试：
ssh -vvv -p 22 USER@10.144.51.4


9. 排错（速查）
配置语法自检：
& "$env:WINDIR\System32\OpenSSH\sshd.exe" -t -f C:\ProgramData\ssh\sshd_config
echo $LASTEXITCODE

前台 Debug（定位绑定/读 key/权限）：
Stop-Service sshd
cd $env:WINDIR\System32\OpenSSH
.\sshd.exe -ddd -f C:\ProgramData\ssh\sshd_config

退出 debug 后恢复服务：
Start-Service sshd

常见错误：



现象
常见原因
修复




Cannot bind any address / ERROR:10049
ListenAddress 填了网段或不存在 IP
填 EasyTier 主机 IP


Authentication failed with public key
公钥位置不对 / 权限不对 / key 粘贴断行
检查管理员组路径 + icacls


密码总失败（只有 PIN）
PIN 不是 Windows 密码
用密钥登录；或设置 Windows Password




10. 收尾加固
确认密钥登录稳定后，关闭密码登录：
PasswordAuthentication no

Restart-Service sshd


11. 检查清单

netstat 仅监听：10.144.51.4:22 LISTENING
ssh -p 22 USER@10.144.51.4 可用密钥登录
若用户在 Administrators 组：公钥在 C:\ProgramData\ssh\administrators_authorized_keys
已设置 PasswordAuthentication no（可选但推荐）




Scoop
Sat, 31 Jan 2026 00:00:00 GMT
Scoop 使用指南
1. 什么是Scoop
Scoop github repo
Scoop 是 Windows 下的命令行包管理器（类似 Debian 的 apt 或 macOS 的 Homebrew）。

非侵入式：默认安装在用户目录 (~/scoop)，无需管理员权限。
环境整洁：自动管理 Path 环境变量，不会污染注册表。
脚本友好：极其适合快速搭建开发环境。


2. 安装与部署

环境要求：PowerShell 5.1+ (Windows 10/11 默认满足)。

2.1 一行命令安装
打开 PowerShell，直接运行：
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
Invoke-RestMethod -Uri https://get.scoop.sh | Invoke-Expression

它将把 Scoop 安装到默认位置：C:\Users\\scoop
如果系统询问你是否更改策略，输入 Y 并回车确认。
2.2 验证安装
安装完成后，输入以下命令查看帮助信息，如果能看到输出说明安装成功：
scoop help

3. 快速上手
3.1 必备组件
安装完 Scoop 后，建议优先安装以下工具以提升体验：
# 安装 Git (所有 bucket 的基础)
scoop install git

# 安装多线程下载器 Aria2 (极大提升下载速度)
scoop install aria2
scoop config aria2-enabled true

3.2 启用常用软件库 (Buckets)
Scoop 默认只有 main 库（精简 CLI 工具）。我们需要启用桶拓展 bucket add 以获取更多常用软件：
# 通用软件库 (浏览器、VS Code 等)
scoop bucket add extras

# 游戏 - 开源及免费软件类视频游戏与游戏相关工具
scoop bucket add games

# 字体库 (Fira Code, JetBrains Mono 等)
scoop bucket add nerd-fonts

# 来自 Nirsoft 的 250 多款应用合集
scoop bucket add nirsoft

# 来自微软的 Sysinternals 工具集
scoop bucket add sysinternals

# nonportable 应用程序（可能触发 UAC 提示）
scoop bucket add nonportable

# 软件历史版本 (如 Python 2.7, Java 8)
scoop bucket add versions

# 适用于大多数版本的 PHP 安装程序
scoop bucket add php

# Java 专用库
scoop bucket add java

3.3 常用命令速查



操作
命令
示例




搜索
scoop search 
scoop search python


搜索
scoop search
显示所有支持的软件


安装
scoop install 
scoop install vscode


更新
scoop update *
更新所有软件


清理
scoop cleanup *
删除旧版本安装包


状态
scoop status
检查是否有更新




4. 开发环境配置 (最佳实践)
4.1 核心编程语言
Python
Scoop 安装的 Python 不会污染全局环境，且支持版本管理。
scoop install python

Go (Golang)
Scoop 会自动配置 GOPATH 和 GOBIN，开箱即用。
scoop install go

Java (JDK)
安装最新的 OpenJDK（需先添加 java bucket）：
scoop install openjdk
# 或者安装特定版本
scoop install openjdk17

Node.js
推荐安装 LTS 版本：
scoop install nodejs-lts

4.2 Rust (推荐方案)
Windows 上安装 Rust 最大的痛点是 C++ 链接器。我们推荐使用 rustup + msvc：

安装 Rustup:scoop install rustup


安装链接器 (Visual Studio Build Tools):
由于 VS Build Tools 体积庞大且配置复杂，不推荐用 Scoop 安装。

下载 Visual Studio Build Tools 安装程序。
勾选 "C++ 桌面开发" 进行安装。


初始化:rustup-init




轻量替代方案：如果你坚决不想装 VS Build Tools，可以安装 gcc 并使用 GNU 工具链：
scoop install gcc
rustup default stable-x86_64-pc-windows-gnu


4.3 C/C++ (MinGW/GCC)
如果你只需要简单的 C/C++ 编译环境（如刷题、简单项目）：
scoop install gcc

这会安装 MinGW-w64 工具链。

5. 命令行效率神器 (CLI Power Tools)
Scoop 是安装现代化 CLI 工具的最佳途径，以下神器强烈推荐：



工具
用途
命令




ripgrep
极速代码搜索 (比 grep 快得多)
scoop install ripgrep


fd
极速文件搜索 (比 find 友好)
scoop install fd


fzf
模糊查找神器
scoop install fzf


bat
带语法高亮的 cat 替代品
scoop install bat


neovim
现代化 Vim 编辑器
scoop install neovim


7zip
命令行解压工具
scoop install 7zip


ffmpeg
视音频处理瑞士军刀
scoop install ffmpeg




6. 进阶技巧
6.1 代理设置
如果下载速度慢，可以为 Scoop 单独设置代理（Aria2 也会生效）：
scoop config proxy 127.0.0.1:10808

6.2 忘记 root 密码? (sudo)
Scoop 有一个名为 sudo 的包，可以让你在非管理员终端临时提权：
scoop install sudo
sudo Set-Time  # 举例

参考链接

Scoop GitHub 仓库




本地上传镜像至服务器
Fri, 02 Jan 2026 00:00:00 GMT
三步走：拉取与打包（本地） -> 传输 -> 加载（服务器）。
第一步：在 Windows 本地拉取并打包镜像
拉取镜像 打开 Windows 的终端（PowerShell 或 CMD），拉取你需要的镜像。 例如：拉取最新的 nginx 镜像
docker pull nginx:latest

⚠️** 架构注意（非常重要）：** 大多数 Windows 电脑是 x86_64 (amd64) 架构。如果你的服务器也是 amd64（如常见的 VPS），直接拉取即可。 但是，如果你的服务器是 ARM 架构（例如甲骨文 ARM 机器、树莓派），你需要指定平台拉取，否则上传后无法运行： docker pull --platform linux/arm64 nginx:latest
将镜像保存为文件 使用 docker save 命令将镜像打包成一个 .tar 文件。
# 语法：docker save -o <文件名.tar> <镜像名:标签>
docker save -o nginx_image.tar nginx:latest

此时，你的当前目录下会生成一个 _nginx_image.tar_ 文件。

第二步：将文件上传到服务器
你可以使用 scp 命令（Windows 10/11 自带）或图形化工具（如 WinSCP、FileZilla）。
方法 A：使用命令行 SCP (推荐) 在 PowerShell 中执行：
# 语法：scp <本地文件路径> <用户名>@<服务器IP>:<服务器目标路径>
scp nginx_image.tar root@192.168.1.100:/root/

(系统会提示你输入服务器密码，输入后回车即可)
方法 B：使用图形化工具 如果你安装了 WinSCP 或 SFTP 等，直接将生成的 .tar 文件拖拽到服务器的某个目录（例如 /root/）即可。

第三步：在服务器上加载镜像
SSH 登录到你的服务器，进入上传文件的目录，执行加载命令。
加载镜像 使用 docker load 命令。
# 语法：docker load -i <文件名.tar>
docker load -i nginx_image.tar

验证是否成功 查看镜像列表，确认镜像已经存在，若已经存在那么可以删掉上传的文件。
docker images

你应该能看到 _nginx_ 及其标签 _latest_ 出现在列表中。
启动容器 现在你可以像平常一样使用这个镜像了：
docker run -d -p 80:80 nginx:latest


💡 进阶技巧：压缩文件体积
docker save 出来的 .tar 文件是未压缩的，通常很大。如果你的上传带宽较小，可以在 Windows 上先压缩一下（需要安装 7-Zip 或使用 WSL）。
如果使用 WSL (Windows Subsystem for Linux) 或 Git Bash： 你可以直接用管道命令压缩：
Bash
docker save nginx:latest | gzip > nginx_image.tar.gz

对应的服务器解压加载命令：
Bash
docker load -i nginx_image.tar.gz

Docker 会自动识别 gzip 格式并解压加载。



docker个人镜像站
Fri, 02 Jan 2026 00:00:00 GMT
我的建议：Github Actions（可以到我的仓库develata/docker-syncer 直接复制模板库）+阿里云ACR。
Github Actions+阿里云ACR
我们将利用 GitHub Actions（由于在海外，能秒下 DockerHub 镜像） 作为搬运工，自动把镜像推送到你的 阿里云 ACR（国内杭州/北京节点），然后你的服务器就可以在国内跑满带宽拉取了。
整个过程完全免费。

第一阶段：配置阿里云 ACR（准备仓库）
目标：在阿里云建立一个“收货地址”。

开通服务

登录 阿里云控制台。
搜索 “容器镜像服务” (ACR) 并进入。
如果提示开通，点击开通（免费）。


创建个人实例（关键！）

点击左侧 “实例列表”。
选择地域：一定要选离你服务器近的国内地域！比如 “华东1（杭州）” 或 “华北2（北京）”。不要选东京/香港，否则国内拉取会慢。Github可以直连dockerhub，虽然 GitHub 连国内阿里云有时候稍慢，但这是发生在 GitHub 的服务器上的，你不需要等待，也不占你的带宽。只要脚本跑完了，镜像就躺在杭州了。国内下载走阿里云国内 BGP 线路，跑满带宽，且极其稳定。
点击页面顶部的 “个人实例” 标签（不要看企业版）。
点击 “创建个人实例” -> 确认协议 -> 确定。


设置访问密码

进入刚创建的实例。
左侧菜单点击 “访问凭证”。
点击右上角 “设置固定密码”。
注意：这个密码是专门给 docker login 用的，不要和你的阿里云登录密码一样，设置一个你记得住的。


创建命名空间

左侧菜单点击 “命名空间” -> “创建命名空间”。
名称：起个你喜欢的名字，比如 my-docker-hub（全网唯一，如果被占用了就换一个）。
设置为 “私有”（如果你不想别人下载）或 “公开”（方便自己随便拉）。建议先设为“私有”。




第二阶段：配置 GitHub（准备搬运工）
目标：雇佣 GitHub 的免费服务器帮我们干活。

创建仓库

登录 GitHub，点击右上角 + -> New repository。
Repository name: 随便填，比如 docker-syncer。
Visibility: Private (建议私有)。
点击 Create repository。


配置阿里云账号密码（Secrets）

在你的 GitHub 仓库页面，点击上方的 Settings。
左侧边栏找到 Secrets and variables -> Actions。
点击 New repository secret，我们需要添加 3 个变量（把阿里云的信息填进去）：






Name
Secret (Value) 填什么？




ALIYUN_USERNAME
你的阿里云全名（在 ACR“访问凭证”页可以看到，通常是 用户名@账号ID
 这种格式）


ALIYUN_PASSWORD
刚才在 ACR 里设置的那个“固定密码”


ALIYUN_NAMESPACE
刚才创建的命名空间名字（例如 my-docker-hub
）


ALIYUN_REGISTRY
你的 ACR 公网地址（在 ACR“概览”页可以看到，例如 registry.cn-hangzhou.aliyuncs.com
）



(注：填完这 4 个 Secret，GitHub 就有权限操作你的阿里云仓库了)

第三阶段：编写搬运脚本
目标：告诉 GitHub 怎么干活。（可以直接复制我的模板库develata/docker-syncer ）

在 GitHub 仓库页面，点击 Actions 标签。
点击 set up a workflow yourself (或者 New workflow)。
将文件名改为 sync-image.yml。
复制粘贴以下代码（我为你写了一个“万能输入框”版本的脚本）：

name: 搬运镜像到阿里云

on:
  workflow_dispatch:
    inputs:
      image_name:
        description: '原镜像名称 (例如: mysql:8.0 或 nginx:latest)'
        required: true
        default: 'nginx:latest'
      new_name:
        description: '保存到阿里云的名称 (留空则与原名一致)'
        required: false
        default: ''

jobs:
  push-to-aliyun:
    runs-on: ubuntu-latest
    steps:
      - name: 登录阿里云 ACR
        uses: docker/login-action@v2
        with:
          registry: ${{ secrets.ALIYUN_REGISTRY }}
          username: ${{ secrets.ALIYUN_USERNAME }}
          password: ${{ secrets.ALIYUN_PASSWORD }}

      - name: 拉取、重命名并推送
        run: |
          # 1. 解析输入
          SRC_IMAGE="${{ inputs.image_name }}"
          
          # 如果用户没填新名字，就提取原镜像的最后一段，比如 mysql:8.0
          if [ -z "${{ inputs.new_name }}" ]; then
            TARGET_IMAGE_TAG=$(echo "$SRC_IMAGE" | awk -F'/' '{print $NF}')
          else
            TARGET_IMAGE_TAG="${{ inputs.new_name }}"
          fi
          
          # 组合阿里云的目标地址
          ALIYUN_TARGET="${{ secrets.ALIYUN_REGISTRY }}/${{ secrets.ALIYUN_NAMESPACE }}/$TARGET_IMAGE_TAG"
          
          echo "正在从 $SRC_IMAGE 拉取..."
          docker pull $SRC_IMAGE
          
          echo "正在推送到 $ALIYUN_TARGET ..."
          docker tag $SRC_IMAGE $ALIYUN_TARGET
          docker push $ALIYUN_TARGET
          
          echo "✅ 成功！国内拉取地址: $ALIYUN_TARGET"


点击右上角 Commit changes 保存。


第四阶段：实际使用（见证奇迹）
现在，你想要拉取任何被墙的镜像，只需要 3 步：

在 GitHub 点一下

进入 GitHub 仓库 -> Actions 标签。
左侧点击 “搬运镜像到阿里云”。
右侧点击 Run workflow。
在弹出框里输入你想拉的镜像，比如 mysql:8.0，然后点击绿色按钮 Run workflow。


等待 1 分钟

你会看到一个圆圈在转，变绿勾✅表示成功。
点进去看日志，它会告诉你最终的国内地址。


在你的国内服务器/电脑上拉取

首次使用需要登录（仅需一次）可以同时登录多个镜像站：



# 这里的地址、用户名填你自己的
sudo docker login --username=你的用户名 你的ACR公网地址例如registry.cn-hangzhou.aliyuncs.com
# 输入密码（那个固定密码）

- **高速拉取**：

# 比如你的命名空间叫 my-docker-hub
sudo docker pull registry.cn-hangzhou.aliyuncs.com/my-docker-hub/mysql:8.0


这个方案的优势

极速：最后一步拉取走的是阿里云国内 BGP 线路，速度取决于你的带宽上限。
私密：你的仓库是私有的，别人拉不了。
灵活：你想拉 gcr.io (谷歌)、quay.io (红帽) 的镜像都可以，只需在 GitHub 输入框里填完整地址（例如 gcr.io/google-samples/hello-app:1.0）。
干净：你的服务器不需要安装任何乱七八糟的代理工具，只需要标准 Docker。

海外服务器中转
方案核心逻辑

架构：国内服务器 -> HTTPS 请求 -> 你的海外 VPS (Nginx + Registry 缓存) -> Docker Hub

实施步骤 (基于 Docker Compose)
假设你的域名是 docker.baidu.com，并且解析到了你的海外 VPS IP。
第一步：在海外 VPS 上部署 Registry (作为缓存)
我们需要部署官方的 registry:2 镜像，并开启 proxy 模式。

创建目录：

mkdir -p /opt/docker-mirror/data
mkdir -p /opt/docker-mirror/config
cd /opt/docker-mirror


创建配置文件 config.yml：

官方 Registry 镜像需要一个配置文件来启用代理模式。
nano config/config.yml

写入以下内容：
version: 0.1
log:
  fields:
    service: registry
storage:
  cache:
    blobdescriptor: inmemory
  filesystem:
    rootdirectory: /var/lib/registry
http:
  addr: :5000
  headers:
    X-Content-Type-Options: [nosniff]
proxy:
  remoteurl: https://registry-1.docker.io # 关键：指向官方 Docker Hub
  username: "" # 如果你有 Docker Hub 账号，可填，否则留空
  password: ""
health:
  storagedriver:
    enabled: true
    interval: 10s
    threshold: 3


**创建 ****docker-compose.yml**：

nano docker-compose.yml

写入以下内容：
version: '3'
services:
  registry-mirror:
    image: registry:2
    container_name: docker-mirror
    restart: always
    ports:
      - "127.0.0.1:5000:5000" # 只监听本地，通过 Nginx 暴露更安全
    volumes:
      - ./config/config.yml:/etc/docker/registry/config.yml
      - ./data:/var/lib/registry # 缓存数据存这里


启动容器：

docker compose up -d

第二步：配置 Nginx 反向代理 + HTTPS + 鉴权
直接暴露 5000 端口很危险，容易被白嫖流量。我们使用 Nginx 来加一层 SSL 和密码保护。

安装 Nginx 和工具 (以 Ubuntu/Debian 为例)：

apt update && apt install nginx apache2-utils -y


生成密码文件：

设置一个用户名（如 myuser）和密码。
htpasswd -Bc /etc/nginx/docker.htpasswd myuser
# 输入两次密码


配置 Nginx 站点：

nano /etc/nginx/sites-available/docker-mirror

写入配置（请替换你的域名）：
server {
    listen 80;
    server_name docker.baidu.com;
    # 强制跳转 HTTPS (建议配合 Certbot 使用)
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    server_name docker.baidu.com;

    # SSL 证书配置 (推荐用 certbot 自动生成，这里仅为占位)
    ssl_certificate /etc/letsencrypt/live/docker.baidu.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/docker.baidu.com/privkey.pem;

    # 优化上传大小
    client_max_body_size 2G;

    location / {
        # 开启 Basic Auth 鉴权
        auth_basic "Registry Realm";
        auth_basic_user_file /etc/nginx/docker.htpasswd;

        proxy_pass http://127.0.0.1:5000;
        proxy_set_header Host $http_host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

注：SSL 证书建议使用 _certbot --nginx_ 一键生成。

重启 Nginx：

ln -s /etc/nginx/sites-available/docker-mirror /etc/nginx/sites-enabled/
nginx -t
systemctl restart nginx

第三步：在国内服务器上使用
现在你的海外 VPS 已经是一个带密码保护的私有镜像站了。
方式 A：作为镜像加速器（配置 daemon.json）
注意：Docker 的 registry-mirrors 配置项不支持带用户名密码的地址。
如果你在 Nginx 开启了 auth_basic，直接配置 registry-mirrors 会拉取失败。
解决方法：

方案 1（推荐 - IP 白名单）：

在 VPS 的 Nginx 配置里，去掉 auth_basic，改为只允许你国内服务器的 IP 访问：
location / {
    allow 1.2.3.4; # 你国内服务器的公网 IP
    deny all;
    proxy_pass http://127.0.0.1:5000;
    ...
}

这样配置后，在国内服务器修改 /etc/docker/daemon.json：
{
  "registry-mirrors": ["https://docker.baidu.com"]
}

然后重启 Docker，以后 docker pull nginx 就会自动走你的 VPS。

方案 2（手动 Login 模式）：

如果你无法固定国内 IP（比如家用宽带），保留 auth_basic。
使用时不能配置为 mirror，而是手动拉取：
# 登录私有仓库
docker login docker.baidu.com
# 输入 myuser 和密码

# 拉取镜像 (注意要加域名)
docker pull docker.baidu.com/library/nginx:latest

极客进阶建议
如果你的 VPS 硬盘比较小，不想存缓存数据，但又想做中转。你可以把第一步中的 registry:2 容器换成一个简单的 SNI Proxy 或者 Nginx Stream Proxy，直接在 TCP 层转发流量到 registry-1.docker.io。
但考虑到你追求“效率”，带缓存的 Registry 方案（即上述方案）是最佳选择。它能避免重复消耗你 VPS 的公网带宽。
GitHub Packages
这是 GitHub 官方提供的容器镜像托管服务。相当于你在 GitHub 上开了一个私有的 Docker Hub
原理：

GitHub Actions 构建/拉取镜像 -> 推送到 ghcr.io (GitHub Container Registry)。
你的服务器 -> 从 ghcr.io 拉取镜像。

核心概念

地址域名：ghcr.io
镜像格式：ghcr.io/你的用户名/镜像名:标签

第一阶段：准备工作（获取访问令牌）
由于 GitHub 不允许在命令行使用账号密码登录，你需要生成一个 PAT (Personal Access Token)。

进入设置：

点击 GitHub 右上角头像 -> Settings。
左侧边栏最底部 -> Developer settings。
左侧 -> Personal access tokens -> Tokens (classic)。
点击 Generate new token (classic)。


配置权限（关键步骤）：

Note: 随便填，例如 docker-login-token。
Expiration: 建议选 No expiration（永久）或者按需设置。
Select scopes (必须勾选以下几项):

✅ write:packages (允许上传镜像)
✅ read:packages (允许下载镜像)
✅ delete:packages (允许删除镜像)
(勾选 _write:packages_ 时，_repo__ 权限通常会自动勾选，保持即可)_。


点击底部的 Generate token。


保存 Token：

立刻复制那个 ghp_ 开头的长字符串。这是你唯一的查看机会，关掉页面就看不到了！



第二阶段：在本地电脑手动推送镜像
假设你在本地上推送镜像。
1. 登录 (Login)
打开终端（Terminal / PowerShell），输入以下命令：
# 格式：echo "你的PAT" | docker login ghcr.io -u 你的用户名 --password-stdin

# 示例：
echo "ghp_AbC123..." | docker login ghcr.io -u develata --password-stdin

提示 _Login Succeeded_ 即为成功。
2. 准备镜像 (Tag)
假设你想把本地的 nginx:latest 上传到 GitHub。GitHub 强制要求镜像名必须包含 ghcr.io/用户名。
# 1. 拉取一个原版镜像
docker pull nginx:latest

# 2. 打标签 (Tag)
# 注意：GitHub 用户名必须全部小写!
docker tag nginx:latest ghcr.io/你的用户名/my-nginx:v1

3. 推送镜像 (Push)
docker push ghcr.io/你的用户名/my-nginx:v1

进度条跑完后，你的镜像就已经存放在 GitHub 的服务器上了。
4. 在 GitHub 查看

进入你的 GitHub 个人主页。
点击顶部的 Packages 标签页。
你应该能看到 my-nginx 这个包。

第三阶段：GitHub Actions 自动构建与推送
这是 GitHub Packages 最强大的地方：无需手动登录，无需配置密码，Actions 脚本里自带权限。
场景：你有一个 GitHub 仓库，里面有 Dockerfile，你希望每次提交代码，GitHub 自动帮你构建镜像并发布到 GHCR。
在你的仓库中创建 .github/workflows/build-push.yml：
name: 构建并推送到 GHCR

on:
  push:
    branches: [ "main" ] # 当 main 分支有代码提交时触发

env:
  REGISTRY: ghcr.io
  IMAGE_NAME: ${{ github.repository }} # 自动获取 "用户名/仓库名"

jobs:
  build-and-push:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write # 关键：赋予 Actions 写入 Packages 的权限

    steps:
      - name: 拉取代码
        uses: actions/checkout@v3

      - name: 登录到 GitHub Container Registry
        uses: docker/login-action@v2
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }} 
          # 注意：GITHUB_TOKEN 是系统内置的，你不需要手动去 Secrets 里设置，直接用就行！

      - name: 提取元数据 (tags, labels)
        id: meta
        uses: docker/metadata-action@v4
        with:
          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}

      - name: 构建并推送
        uses: docker/build-push-action@v4
        with:
          context: .
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}

效果：你只管写代码，Git Push 之后，镜像就自动出现在你的 Packages 列表里了。
第四阶段：镜像权限管理（私有 vs 公开）
默认情况下，你推送的镜像是 **私有（Private）**的。
1. 私有镜像 (Private)

下载方式：必须先 docker login，且拥有权限。
适用场景：企业内部代码、个人私密服务。

2. 公开镜像 (Public)
如果你想做开源，或者方便服务器免登录拉取：

进入 GitHub 个人主页 -> Packages。
点击你刚才上传的镜像进入详情页。
点击右侧边栏底部的 Package settings。
找到 "Change visibility" 区域。
将 Visibility 改为 Public。

改为 Public 后：
任何人在任何服务器上，都可以直接拉取：
docker pull ghcr.io/你的用户名/my-nginx:v1
# 不需要 login，不需要密码

第五阶段：从 DockerHub 搬运到 GHCR
利用 GitHub Actions 作为云端搬运工。
原理：
GitHub Action 服务器 (美国) -> docker pull (从 DockerHub) -> docker tag (改名) -> docker push (到 GHCR)。
1. 创建 Action 脚本
在你的一个 GitHub 仓库中，创建文件 .github/workflows/sync-to-ghcr.yml：
name: 镜像搬运工 (DockerHub -> GHCR)

on:
  workflow_dispatch:
    inputs:
      image_name:
        description: '原镜像名称 (例如: mysql:8.0)'
        required: true
        default: 'nginx:alpine'
      target_name:
        description: '保存名称 (可选，留空则保持原名)'
        required: false

env:
  REGISTRY: ghcr.io

jobs:
  mirror:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write # 必须权限

    steps:
      # 1. (可选) 登录 DockerHub —— 防止拉取时被限流
      # 如果你不需要，可以删除这一步，但保留着更稳
      - name: 登录 DockerHub
        uses: docker/login-action@v2
        with:
          username: ${{ secrets.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}
        # 如果没有配置 Secrets，这一步会跳过或报错；
        # 即使报错，只要不是"required"，通常不影响后续，建议去 Secrets 配个免费号
        continue-on-error: true 

      # 2. 登录 GHCR
      - name: 登录 GHCR
        uses: docker/login-action@v2
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      # 3. 核心逻辑
      - name: 拉取、重命名并推送
        run: |
          # --- 变量准备 ---
          SRC_IMAGE="${{ inputs.image_name }}"
          
          # 判断是否自定义了名称
          if [ -z "${{ inputs.target_name }}" ]; then
            # 提取原镜像名 (例如: library/nginx:alpine -> nginx:alpine)
            IMAGE_TAG=$(echo "$SRC_IMAGE" | awk -F'/' '{print $NF}')
          else
            IMAGE_TAG="${{ inputs.target_name }}"
          fi

          # 组合基础地址
          # 技巧: 直接在这里把整个字符串转为小写，一劳永逸
          FULL_TARGET="${{ env.REGISTRY }}/${{ github.repository_owner }}/$IMAGE_TAG"
          TARGET_IMAGE=$(echo "$FULL_TARGET" | tr '[:upper:]' '[:lower:]')

          # --- 执行命令 ---
          echo "1️⃣ 正在从 DockerHub 拉取: $SRC_IMAGE"
          docker pull $SRC_IMAGE

          echo "2️⃣ 正在打标签: $TARGET_IMAGE"
          docker tag $SRC_IMAGE $TARGET_IMAGE

          echo "3️⃣ 正在推送到 GHCR..."
          docker push $TARGET_IMAGE

          echo "✅ 完成! 你的拉取地址是:"
          echo "docker pull $TARGET_IMAGE"

2. 如何使用

点击仓库顶部的 Actions。
左侧选择 “镜像搬运工”。
点击 Run workflow。
输入 redis:7.0，点击运行。
一分钟后，你的 GHCR 里就有了 ghcr.io/你的用户名/redis:7.0。

GitHub Packages 的上限是多少？（避坑必读）
GitHub Packages 的计费策略分为 “公开包 (Public)” 和 “私有包 (Private)”，区别极其巨大。
存储空间 (Storage)



类型
限制/额度
评价




公开包 (Public)
完全免费，无限制
⭐⭐⭐⭐⭐


私有包 (Private)
500 MB (免费版)
❌ ****



2 GB (Pro 版)
勉强够用




警告：Docker 镜像通常很大。一个 mysql:8.0 大约 500MB，一个 pytorch 镜像可能 2GB+。
后果：如果你把仓库设为私有，传 1-2 个镜像你的免费额度就爆了。一旦超额，GitHub Actions 可能会报错，或者要求你绑定信用卡扣费（$0.25 / GB / 月）。

从 GitHub Packages 下载镜像所产生的流量（出站流量）：



类型
限制/额度
评价




公开包 (Public)
完全免费，无限制
⭐⭐⭐⭐⭐


私有包 (Private)
1 GB / 月 (免费版)
❌ ****



10 GB / 月 (Pro 版)
也不多




后果：如果你设为私有，然后在服务器上 docker pull，1GB 流量瞬间用完（拉两次 MySQL 就没了）。

基于上述限制，如果你决定使用 GHCR，请务必“公开”
注
如果你的服务器在海外，GHCR 是最好用的（比 DockerHub 好用，因为 Actions 集成度高）。如果你的服务器在国内，GHCR 仅适合作为代码构建的产物存储，最终运行还是建议同步到阿里云 ACR。
GitHub Actions+网盘
这个方案是利用 GitHub Actions 的免费且高速的海外网络，帮你把 Docker Hub 的镜像下载下来，打包成文件，然后自动上传到你的网盘。
这样，你的国内服务器只需要从网盘（Alist 挂载）里读取文件即可，全程跑满国内带宽。
Cloudflare中转
根据 Cloudflare 协议 中，2.2.1 第 (j) use the Services to provide a virtual private network or other similar proxy services.
使用本服务可能存在被 Cloudflare 封号的潜在风险，请自行斟酌使用风险。
如果你选择了“根据主机名选择对应的上游地址”方式部署，你可能会:
被 Netcraft 扫描到，收到警告邮件
被 Netcraft 同步到 Google Safe Browsing 标记为钓鱼网站
被 Netcraft 投诉到 Cloudflare 标记为钓鱼网站, 无法正常 pull 镜像
收到律师函

基于 Cloudflare Workers 的方案与之前的“阿里云存储”方案逻辑完全不同。

阿里云方案：是仓库（Storage）。你需要先把镜像“搬”进去，才能下载。
Cloudflare 方案：是即时代理（Proxy）。它不需要搬运，你请求什么，它就帮你去 DockerHub 抓什么，然后转发给你。它是一个“梯子”。

由于你已经有了自己的域名 baidu.com，这个方案实施起来非常快，5 分钟内即可完成。
我们采用目前社区维护最活跃、功能最全的开源项目：cmliu/CF-Workers-docker.io。
第一步：创建 Cloudflare Worker

登录 Cloudflare Dashboard。
左侧菜单点击 Workers & Pages。
点击 Create (创建应用) -> Create Worker (创建 Worker)。
名字随便起，例如 docker-proxy，点击 Deploy (部署)。

此时你会得到一个 _xxx.workers.dev_ 的地址，这个地址在国内是被墙的，先不管它。



第二步：部署代理代码

进入刚才创建的 Worker，点击 Edit code (编辑代码)。
删除 编辑器里原本自带的所有代码。
去 GitHub 复制大神写好的代码：

打开链接：worker.js 源码
全选 (Ctrl+A) -> 复制。


回到 Cloudflare 编辑器，粘贴代码。
点击右上角的 Deploy 保存。

第三步：绑定你的域名 (关键！)
因为 Cloudflare 自带的 *.workers.dev 域名在国内无法访问，必须绑定你自己的域名。

回到 Worker 的详细页面，点击 Settings (设置) -> Triggers (触发器)。
点击 Add Custom Domain (添加自定义域名)。
输入你想用的二级域名，例如：docker.baidu.com。

前提：你的域名 baidu.com 必须是托管在 Cloudflare 上的（DNS 解析在 CF）。如果不是，你需要先将域名的 DNS 服务器改为 Cloudflare。


点击 Add Custom Domain。

等待几分钟，直到状态变为 Active (有效)。



第四步：如何使用？
现在，docker.baidu.com 就是你专属的 Docker Hub 加速器了。你有两种用法：
用法 A：直接替换前缀 (临时用)
原本你要拉取 nginx：
docker pull nginx:latest

现在改成：
docker pull docker.baidu.com/library/nginx:latest

(注意：官方镜像如 nginx, mysql 需要加 _/library/_ 前缀，或者代码里有自动补全逻辑)
用法 B：配置镜像加速器 (推荐，永久生效)
这样配置后，你不需要改任何命令，直接 docker pull nginx 就会自动走你的 CF 代理。

修改 Docker 配置：

编辑服务器上的 /etc/docker/daemon.json 文件（如果没有就新建）：
{
  "registry-mirrors": [
    "https://docker.baidu.com"
  ]
}


重启 Docker：

sudo systemctl daemon-reload
sudo systemctl restart docker


验证：

输入 docker info，看输出信息的最后几行，如果有 Registry Mirrors 并且显示了你的域名，说明成功了。
进阶优化：防止被滥用 (可选)
既然你的域名是公开的，别人也能用你的流量。虽然 Cloudflare 每天有 10 万次免费请求，但为了安全，建议加个密码。

回到 Cloudflare Worker 的代码编辑页面。
在代码的最开头（通常在前几行），找到 const TOKEN = ''; 这种变量定义（不同版本的代码位置可能不同，cmliu 的代码通常支持环境变量）。
推荐做法：使用环境变量配置。

Worker 页面 -> Settings -> Variables.
添加变量：

TOKEN: 设置一个密码，例如 mypassword123.


保存并部署。



设置了密码后怎么用？
你就不能用“用法 B”了，必须用 docker login：
docker login docker.baidu.com
# 用户名：随便填 (例如 admin)
# 密码：填刚才设置的 TOKEN (mypassword123)

登录后，再 docker pull docker.baidu.com/library/nginx。
Github Actions双重同步到阿里云与Github Packages
先搭建好github packages和阿里云ACR的actions在一个仓库中
在同一仓库中（也可以在任意仓库中）新建一个 .github/workflows/sync-double.yml
name: 双重同步 (阿里云 + GHCR)

on:
  workflow_dispatch:
    inputs:
      image_name:
        description: '原镜像名称 (如: mysql:8.0)'
        required: true
        default: 'nginx:alpine'

env:
  # 阿里云配置
  ALIYUN_REGISTRY: ${{ secrets.ALIYUN_REGISTRY }}
  ALIYUN_NAMESPACE: ${{ secrets.ALIYUN_NAMESPACE }}
  # GHCR 配置
  GHCR_REGISTRY: ghcr.io

jobs:
  double-push:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write # 必须赋予写 GHCR 的权限

    steps:
      - name: 1. 登录阿里云
        uses: docker/login-action@v2
        with:
          registry: ${{ env.ALIYUN_REGISTRY }}
          username: ${{ secrets.ALIYUN_USERNAME }}
          password: ${{ secrets.ALIYUN_PASSWORD }}

      - name: 2. 登录 GHCR
        uses: docker/login-action@v2
        with:
          registry: ${{ env.GHCR_REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: 3. 拉取原镜像
        run: |
          docker pull ${{ inputs.image_name }}

      - name: 4. 推送到 阿里云
        run: |
          # 提取镜像名和标签 (例如 mysql:8.0)
          IMAGE_TAG=$(echo "${{ inputs.image_name }}" | awk -F'/' '{print $NF}')
          
          # 组合地址
          ALI_TARGET="$ALIYUN_REGISTRY/$ALIYUN_NAMESPACE/$IMAGE_TAG"
          
          echo "🚀 推送至阿里云: $ALI_TARGET"
          docker tag ${{ inputs.image_name }} $ALI_TARGET
          docker push $ALI_TARGET

      - name: 5. 推送到 GHCR
        run: |
          IMAGE_TAG=$(echo "${{ inputs.image_name }}" | awk -F'/' '{print $NF}')
          
          # 关键步骤：GitHub 用户名转小写 (GHCR 强制要求)
          OWNER=$(echo "${{ github.repository_owner }}" | tr '[:upper:]' '[:lower:]')
          
          # 组合地址
          GHCR_TARGET="$GHCR_REGISTRY/$OWNER/$IMAGE_TAG"
          
          echo "🚀 推送至 GHCR: $GHCR_TARGET"
          docker tag ${{ inputs.image_name }} $GHCR_TARGET
          docker push $GHCR_TARGET

      - name: 6. 总结
        run: |
          echo "✅ 同步完成！"




iptables
Fri, 02 Jan 2026 00:00:00 GMT
这份教程针对 Debian/Ubuntu 系 VPS（最常见的服务器系统）
一、 新机开荒：30秒一键初始化
在一台全新的 VPS 上，按顺序执行以下命令，即可完成“安装 + 基础配置 + 持久化”。
1. 安装持久化工具
sudo apt update
# 安装过程中遇到问询弹窗，一路选 
sudo apt install iptables-persistent -y

2. 一键注入“安全模板”
警告：如果你修改了 SSH 端口（不是 22），请修改下方第 5 行的 22。
直接复制整段粘贴进终端：
# 1. 清空现有规则（防止冲突）
iptables -F
iptables -X

# 2. 【核心】允许已建立的连接（防止断连）
iptables -A INPUT -m conntrack --ctstate ESTABLISHED,RELATED -j ACCEPT

# 3. 【核心】允许 SSH (如果是 1228 端口请自行修改)
iptables -A INPUT -p tcp --dport 22 -j ACCEPT

# 4. 允许基础服务 (HTTP/HTTPS/Ping/Loopback)
iptables -A INPUT -p tcp --dport 80 -j ACCEPT
iptables -A INPUT -p tcp --dport 443 -j ACCEPT
iptables -A INPUT -p icmp -j ACCEPT
iptables -A INPUT -i lo -j ACCEPT

# 5. 【核心】封锁大门 (默认拒绝)
iptables -P INPUT DROP
iptables -P FORWARD ACCEPT
iptables -P OUTPUT ACCEPT

# 6. 保存规则
netfilter-persistent save


二、 指令速查字典 (Cheat Sheet)
1. 查看规则 (Query)
最常用的两条，死记硬背：
Bash
# 简洁版：看有什么端口开了
iptables -nvL

# 运维版：显示行号 (删除、插入规则时必须用)
iptables -nvL --line-numbers

2. 放行端口 (Allow)
注意：-A 表示追加到最后。如果你的默认策略是 DROP，追加是没问题的。
Bash
# 放行 TCP 端口 (如 8080)
iptables -A INPUT -p tcp --dport 8080 -j ACCEPT

# 放行 UDP 端口 (如 EasyTier/WireGuard)
iptables -A INPUT -p udp --dport 10110 -j ACCEPT

# 放行特定 IP 访问特定端口 (只允许 IP 1.2.3.4 连 SSH)
iptables -A INPUT -p tcp -s 1.2.3.4 --dport 22 -j ACCEPT

3. 删除规则 (Delete)
必须先用 iptables -nvL --line-numbers 查出行号。
Bash
# 删除 INPUT 链的第 5 行
iptables -D INPUT 5

4. 插入规则 (Insert)
场景：当你需要把规则放到最前面（优先级最高），或者 Fail2ban 没有自动把链插到最前面时。
Bash
# 插队到第 1 行
iptables -I INPUT 1 -p tcp --dport 9000 -j ACCEPT

5. 保存与重载 (Persistence)
iptables 重启即失效，修改后必须保存。
Bash
# 保存当前规则到硬盘
netfilter-persistent save

# 从硬盘重新加载规则 (撤销刚才未保存的修改)
netfilter-persistent reload


三、 救命锦囊：被自己锁外面了怎么办？
如果你不小心执行了 iptables -P INPUT DROP 但没放行 SSH，连接断开。
解决方法：

去云服务商（阿里云/腾讯云/AWS）的网页控制台，找到 VNC 控制台 (Web 终端)。
登录进去（VNC 不走网络协议，不受 iptables 影响）。
执行急救命令，清空防火墙：

Bash
# 把默认策略改回 ACCEPT
iptables -P INPUT ACCEPT
# 清空所有规则
iptables -F
# 保存
netfilter-persistent save

四、 常用场景模板

Docker 场景：Docker 会自己接管 iptables，不要轻易执行 iptables -F（会把 Docker 的网断掉）。如果非要重置，建议重启 Docker 服务。
多端口放行：

Bash
iptables -A INPUT -p tcp -m multiport --dports 21,22,80,443 -j ACCEPT


屏蔽恶意 IP：

Bash
iptables -I INPUT 1 -s 123.123.123.123 -j DROP




UFW指令大全
Tue, 02 Dec 2025 17:30:00 GMT
UFW (Uncomplicated Firewall) 指令大全
1. UFW 常用指令 (高频精简版)



指令
描述
常用示例




ufw enable
启用防火墙 (开机自启)
sudo ufw enable


ufw disable
禁用防火墙
sudo ufw disable


ufw status
查看状态及规则
sudo ufw status


ufw reload
重载配置 (不中断连接)
sudo ufw reload


ufw allow
允许外部访问端口
sudo ufw allow 22/tcp (开放 SSH)


ufw deny
拒绝外部访问端口
sudo ufw deny 80


ufw delete
删除某条规则
sudo ufw delete allow 22


ufw reset
重置所有规则至默认
sudo ufw reset (慎用，需重新配置)




2. UFW 全面指令 (分类速查)
2.1 基础控制与状态 (Basic Control)



指令
描述




ufw enable
开启防火墙 (默认策略：拒绝入站，允许出站)


ufw disable
关闭防火墙


ufw reload
重新加载配置文件


ufw reset
重置防火墙配置为默认状态 (会清空所有自定义规则)


ufw status
显示防火墙状态和当前激活的规则


ufw status verbose
显示详细状态 (包括默认策略、日志级别)


ufw status numbered
显示带编号的规则列表 (常用于删除指定规则)



2.2 端口与协议规则 (Ports & Protocols)



指令
描述




ufw allow 
允许访问指定端口 (TCP/UDP)


ufw allow /tcp
仅允许 TCP 协议访问指定端口


ufw allow /udp
仅允许 UDP 协议访问指定端口


ufw deny 
拒绝访问指定端口


ufw reject 
拒绝访问并返回“不可达”消息 (比 deny 更明确)


ufw allow :/tcp
允许一个端口范围 (如 ufw allow 8000:8010/tcp)


ufw allow 
允许常见服务名 (如 ufw allow ssh, ufw allow http)



2.3 IP地址与高级规则 (IP & Advanced)



指令
描述




ufw allow from 
允许特定 IP 访问所有端口


ufw deny from 
封锁特定 IP


ufw allow from 
允许特定子网 (如 192.168.1.0/24)


ufw allow from  to any port 
允许特定 IP 访问特定端口 (最常用安全策略)


ufw deny from  to any port 
禁止特定 IP 访问特定端口


ufw allow in on 
允许特定网卡接口入站 (如 ufw allow in on eth0)


ufw allow out on 
允许特定网卡接口出站



2.4 规则管理与删除 (Management & Deletion)



指令
描述




ufw delete allow 
删除对应的允许规则 (需完整匹配原命令)


ufw delete 
根据编号删除规则 (先用 ufw status numbered 查看)


ufw insert  
在指定位置插入规则 (如 ufw insert 1 allow 80)



2.5 默认策略与日志 (Default Policy & Logging)



指令
描述




ufw default deny incoming
设置默认入站策略为“拒绝” (推荐)


ufw default allow incoming
设置默认入站策略为“允许” (不安全)


ufw default allow outgoing
设置默认出站策略为“允许”


ufw default deny outgoing
设置默认出站策略为“拒绝” (高安保环境)


ufw logging on
开启日志记录


ufw logging off
关闭日志记录


ufw logging low/medium/high
设置日志详细级别



2.6 应用配置文件 (App Profiles)
UFW 可以读取 /etc/ufw/applications.d 中的预设配置。



指令
描述




ufw app list
列出所有已知的应用配置


ufw app info 
查看指定应用的端口配置详情


ufw app update 
更新应用配置


ufw allow 
允许该应用的所有预设端口 (如 ufw allow 'Nginx Full')






iptables 指令大全
Tue, 02 Dec 2025 17:30:00 GMT
iptables 指令大全
1. 常用核心指令 (高频精简版)



指令/参数
语法结构
描述




-L (List)
iptables -L -n -v
查看所有规则 (数字格式/详细)


-F (Flush)
iptables -F
清空当前表的所有规则


-A (Append)
iptables -A INPUT -s  -j DROP
在链末尾追加规则 (如封禁IP)


-I (Insert)
iptables -I INPUT 1 -p tcp --dport 80 -j ACCEPT
在链首(或指定位置)插入规则


-D (Delete)
iptables -D INPUT <编号>
删除指定编号的规则


-P (Policy)
iptables -P INPUT DROP
设置默认策略 (如默认拒绝所有入站)


-s (Source)
iptables -A INPUT -s 192.168.1.100 -j ACCEPT
匹配源 IP 地址


--dport
iptables -A INPUT -p tcp --dport 22 -j ACCEPT
匹配目标端口 (需配合 -p)


save
iptables-save > /etc/iptables.rules
导出/保存当前规则


restore
iptables-restore < /etc/iptables.rules
导入/恢复规则




2. iptables 全面指令 (分类速查)
2.1 链与表管理 (Chains & Tables)
管理 Filter(默认), NAT, Mangle 等表及链的操作。



指令/参数
语法结构
描述




-t
iptables -t nat -L
指定操作的表 (filter/nat/mangle/raw)


-L
iptables -L [链名] [选项]
列出规则 (常用参数 -n -v --line-numbers)


-F
iptables -F [链名]
清空规则 (Flush)


-Z
iptables -Z [链名]
计数器归零 (Zero)


-N
iptables -N <新链名>
新建自定义链


-X
iptables -X [链名]
删除自定义链 (链必须为空)


-E
iptables -E <旧名> <新名>
重命名自定义链


-P
iptables -P <链名> <动作>
设置链的默认策略 (ACCEPT/DROP)



2.2 规则操作 (Rule Management)
针对具体规则的增删改。



指令/参数
语法结构
描述




-A
iptables -A <链名> <规则>
追加规则到链尾 (Append)


-I
iptables -I <链名> [编号] <规则>
插入规则 (默认插到第一行)


-D
iptables -D <链名> <编号/规则>
删除规则 (按编号或匹配内容)


-R
iptables -R <链名> <编号> <新规则>
替换/修改指定行号的规则


-C
iptables -C <链名> <规则>
检查规则是否存在 (Check)



2.3 匹配条件 (Matching Specs)
定义什么样的流量会被捕获。



指令/参数
语法结构
描述




-p
iptables -A INPUT -p tcp
匹配协议 (tcp/udp/icmp/all)


-s
iptables -A INPUT -s 192.168.1.0/24
匹配源 IP 或网段 (Source)


-d
iptables -A OUTPUT -d 8.8.8.8
匹配目标 IP 或网段 (Destination)


-i
iptables -A INPUT -i eth0
匹配入站网卡接口 (Input Interface)


-o
iptables -A OUTPUT -o eth0
匹配出站网卡接口 (Output Interface)


--sport
... -p tcp --sport 22
匹配源端口 (Source Port)


--dport
... -p tcp --dport 80
匹配目标端口 (Destination Port)


--icmp-type
... -p icmp --icmp-type 8
匹配 ICMP 类型 (如 8 为 ping 请求)



2.4 高级模块匹配 (Modules)
使用 -m 调用扩展模块进行复杂匹配。



指令/参数
语法结构
描述




-m state
... -m state --state ESTABLISHED,RELATED
匹配连接状态 (常用：允许已建立的连接)


-m multiport
... -m multiport --dports 80,443,22
匹配多个不连续端口


-m mac
... -m mac --mac-source 
匹配源 MAC 地址


-m limit
... -m limit --limit 5/min
速率限制 (防 DDoS 常用)


-m string
... -m string --algo bm --string "test"
匹配数据包中的字符串


-m time
... -m time --timestart 08:00 --timestop 18:00
按时间段匹配


-m iprange
... -m iprange --src-range 192.168.1.5-192.168.1.10
匹配 IP 地址范围



2.5 动作与目标 (Targets -j)
匹配到流量后执行的动作。



指令/参数
语法结构
描述




ACCEPT
-j ACCEPT
允许数据包通过


DROP
-j DROP
直接丢弃数据包 (不回传任何信息)


REJECT
-j REJECT
拒绝并回传 ICMP 错误信息


LOG
-j LOG --log-prefix "IPTABLES: "
记录日志到 syslog (不中断处理)


SNAT
-t nat ... -j SNAT --to-source 
源地址转换 (用于静态 IP 网关)


DNAT
-t nat ... -j DNAT --to-destination 
目标地址转换 (端口转发)


MASQUERADE
-t nat ... -j MASQUERADE
动态源地址伪装 (用于动态 IP 网关)


REDIRECT
-t nat ... -j REDIRECT --to-port <端口>
本机端口重定向 (透明代理常用)



2.6 持久化与保存 (Persistence)
iptables 规则重启后默认清空，需手动保存。



指令
语法结构
描述




iptables-save
iptables-save > /etc/iptables.v4
将当前运行规则输出到文件


iptables-restore
iptables-restore < /etc/iptables.v4
从文件恢复规则


netfilter-persistent
netfilter-persistent save
(Debian/Ubuntu) 保存当前规则 (需安装包)


service iptables
service iptables save
(CentOS 6/Old RHEL) 保存规则






3-2-1 备份法
Sat, 29 Nov 2025 22:23:00 GMT
“3-2-1 备份法”是数据备份领域公认的黄金法则。
3-2-1 备份法具体是指：
3：存储 3 份完整的数据
2：使用 2 种不同的存储介质
1：至少 1 份异地备份（Off-site）
3：存储 3 份完整的数据
你的数据至少要有三个副本。
第 1 份： 原件（比如你正在修改的论文文档，存在你电脑硬盘里）。
第 2 份： 备份 A。
第 3 份： 备份 B。
为什么要 3 份？ 如果只有 1 份备份，万一你要恢复数据的时候发现备份文件损坏了（这种情况比你想象的更常见），你就彻底完蛋了。3 份能将这种概率降到极低。
2：使用 2 种不同的存储介质
这 3 份数据，不能全都在同一个地方，至少要横跨两种不同的设备或媒介。
错误示范： 原件在电脑 C 盘，备份在电脑 D 盘。
风险： 电脑主板烧了、电源短路、或者被偷了，两份数据同时完蛋。
正确示范：
介质 1：电脑硬盘（原件）。
介质 2：移动硬盘 / U盘 / NAS / 光盘（备份）。
为什么要不同介质？ 主要是为了防范硬件故障。不同设备的寿命和故障模式是不一样的。
1：至少 1 份异地备份（Off-site）
这 3 份数据中，至少要有 1 份是不放在你身边的（物理位置隔离）。
什么是异地： 云端（网盘）、位于另一个城市的服务器、或者哪怕是你放在办公室抽屉里的硬盘（如果你电脑在宿舍）。
错误示范： 电脑和移动硬盘都放在同一个背包里。
风险： 背包丢了，或者宿舍发生火灾/水灾，所有数据物理毁灭。
为什么要异地？ 这是为了防范物理灾难（火灾、盗窃、洪水）以及勒索病毒（如果所有硬盘都插在电脑上，病毒会把它们一起加密，但云端通常有历史版本回滚功能）。



新服务器必做
Sat, 29 Nov 2025 00:00:00 GMT
debian,ubuntu
一、更新组件，包管理
要在Ubuntu系统上更新软件包，可以使用以下命令：
不推荐，安装时间太长了
sudo apt update && sudo apt upgrade -y 

推荐用下面两条
sudo apt update  #这个命令会更新软件包列表，让系统知道有哪些软件包可以更新。
sudo apt upgrade --only-upgrade #这个命令会安装所有可用的软件包更新。

二、常用工具
1、VIM编辑器【不需要可以装nano(不如nano)】
检查有没有安装VIM（Ubuntu是默认自带nano的）
vim --version

没有的话就用命令安装
apt install vim 

配置VIM为默认的系统编辑器。

很简单，执行这条命令，选择 Vim，以后凡是自动调用编辑器的地方，都会用 Vim 啦。
sudo update-alternatives --config editor

2、安装 command-not-found【不需要可以不装】
很多服务器提供商可能会提供精简版本的 Ubuntu，于是一些实用的命令行工具并不会预装。比如command-not-found，它可以当你在打命令时，提示对应的但没有安装的 package。
sudo apt install command-not-found

安装完后，就可以在使用命令行的过程中更加方便了。
三、添加普通用户
如果本身就不是root就不用
1、添加普通用户
使用adduser创建用户，命令如下：
adduser newuser

newuser为要创建的账号名，修改为自己想要的用户名。
期间需要输入两次密码。第一次用于设置密码，第二次用于确认密码。
注意，输入密码时，看不见输入的字符。输入后回车即可。
设置密码后，需要设置账户信息，这里可以采用默认，全部回车，最后输入y确认即可：
添加用户后，默认会在/home路径下创建一个与用户名相同的用户目录。
2、给新用户添加管理权限
如果希望新创建的用户具有管理权限，将用户添加到sudo组即可！
将新用户添加到 sudo 组，命令如：
adduser newuser sudo

3、账号切换
由root账号切换到普通账号：
sudo su newuser

由普通账号切换到root账号：
sudo -i

注意：切换到root账号时，需要输入当前账号的密码。
四、防火墙配置
如果自带防火墙就不用
安装ufw：
要在 Ubuntu 上使用 ufw（Uncomplicated Firewall）开启端口 22、80 和 443，你可以按照以下步骤进行配置：
检查 ufw 是否安装：
如果尚未安装 ufw，你可以使用以下命令安装：
sudo apt install ufw

开启端口：
开启端口 22：SSH
sudo ufw allow 22

开启端口 80：http
sudo ufw allow 80

开启端口 443：HTTPS
sudo ufw allow 443

常用端口



21(Ftp)
22(Ssh)
23(Telnet)
25(Smtp)
8888(BT)




80(Http)
110(Pop3)
143(IMAP)
443(Https)
445(共享)


1433(MSSQL)
3306(MYSQL)
3311(康乐)
3312(康乐)
3389(远程桌面)



启用防火墙：
启用 ufw 防火墙：
sudo ufw enable

检查配置：
可以运行
sudo ufw status

来查看防火墙的状态和已开启的端口。

参考文章
https://blog.csdn.net/qq_53679247/article/details/128374607
五、配置 SSH 登录及 SSH Server 安全设定
ubuntu24需要额外做本节最后面的配置。
输入以下命令来编辑 SSH 配置文件
两个功能一样的，若未安装vim，默认nano
sudo nano /etc/ssh/sshd_config

sudo vim /etc/ssh/sshd_config

禁用root身份登录
编辑 SSH 配置文件
找到PermitRootLogin Yes这一项，然后把它后面的设定值改为no即可。

如下：
PermitRootLogin no

SSH端口号更改
编辑 SSH 配置文件
Port 22

SSH端口号22改为其他数字，注意了，改成其他端口后，记得防火墙设置也要更新。

Port [SSH端口号，最好在10000以上]
然后重启 SSH Server 生效：
sudo systemctl restart sshd.service

禁止密码登录，改为密钥登录（麻烦，可跳过）
先在windows端生成 ssh 公私钥对
ssh-keygen -t rsa -f %USERPROFILE%\.ssh\ali_id_rsa_admin

或在linux端生成 ssh 公私钥对（但要记得保存下来）
ssh-keygen -t rsa -f ~/.ssh/id_rsa_xxxx

-f表示更友好地输出方式，后面跟的是储存目录
在用户目录下创建authorized_keys文件，并将公钥（pub结尾）的内容粘入authorized_keys文件中
mkdir -p ~/.ssh
touch ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys

再编辑 SSH 配置文件
把 PasswordAuthentication 设置成 no，禁止密码登录：
PasswordAuthentication no

把 PubkeyAuthentication 设置成 yes，允许密钥登录：
PubkeyAuthentication yes

ubunutu24
因为新增了 ssh.socket  ，需要关掉或者打开强制的ipv4，如果不强制ipv4就无法访问(bug)
sudo systemctl edit ssh.socket

在空白处插入如下代码。111改成SSH端口，测试完成之后再删除22那里
[Socket]
ListenStream=
# 专门负责 IPv4
ListenStream=0.0.0.0:111
# 专门负责 IPv6
ListenStream=[::]:111

# 建议 22 端口也保持双栈（为了备用通道的安全）
ListenStream=0.0.0.0:22
ListenStream=[::]:22

六、自定义shell 界面安装【不需要可以不装】
安装 oh-my-zsh
sh -c "$(curl -fsSL https://raw.github.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

其他主题、插件等配置参考：

zsh 安装与配置：9步打造高效命令行 - HackerNeo

Tmux

Tmux 是一个终端多路复用器，可以从单个屏幕创建、访问和控制多个终端。 Tmux 可能会与屏幕分离，并继续在后台运行，然后重新连接。
每当 tmux 启动时，它都会创建一个带有单个窗口的新会话并将其显示在屏幕上。屏幕底部的状态行显示当前会话的信息，用于输入交互式命令。
在本指南中，我将与您分享 Tmux 备忘单，以帮助您在 Linux 或 Unix 机器上开始使用 tmux。在进入备忘单部分之前，我们先来看看如何在 Linux 上安装 tmux。
来源： 一台新到手的VPS服务器必做十二项配置（以Ubuntu为例） - #54 by shayne

Thefuck

来自：https://linux.do/t/115839/105的命令补全工具

github.com
GitHub - nvbn/thefuck: Magnificent app which corrects your previous...

Magnificent app which corrects your previous console command.
七、Docker配置【不需要可以不装】
1、安装 Docker
官方地址：https://docs.docker.com/install/linux/docker-ce/ubuntu/

快速安装
curl https://get.docker.com | sh

首先安装基本环境：
sudo apt install \
        apt-transport-https \
        ca-certificates \
        curl \
        software-properties-common

再安装 key：
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -

再增加 Docker 官方源：
sudo add-apt-repository \
     "deb [arch=amd64] https://download.docker.com/linux/ubuntu \
     $(lsb_release -cs) \
     stable"

最后就可以安装 Docker 了，我一般也同时会用 Docker Compose，一起安装上去吧！
sudo apt update
sudo apt install docker-ce docker-compose

安装好 Docker 以后，记得将当前用户加到 docker 用户组里去（如果你不想每次都用 sudo 用 Docker 的话）
sudo gpasswd docker -a username

2、Docker日志管理
全局配置日志大小限制
创建或修改文件 /etc/docker/daemon.json，并增加以下配置（3份日志、每份10M）。
{
        "log-driver": "json-file",
        "log-opts": {
                "max-file": "3",
                "max-size": "10m"
        }
}

随后重启 Docker 服务
sudo systemctl daemon-reload
sudo systemctl restart docker

不过已存在的容器不会生效，需要重建才可以！
单个容器日志大小限制
写在docker-compose中
logging:
  driver: json-file
  options:
    max-size: "100m"
    max-file: "3"

八、swap配置【不需要可以不做，但是很重要】
sudo swapoff -a   # 删除原分区
sudo dd if=/dev/zero of=/root/swapfile bs=1M count=5120  # 配置新分区大小MB，一般为内存的2-3倍
sudo chmod 600 /root/swapfile
sudo mkswap /root/swapfile
sudo swapon /root/swapfile

最后设置开机启动：可以编辑 /etc/fstab 文件，把最后一行改成：
/root/swapfile swap swap defaults 0 0

参考文章：
https://skywt.cn/blog/changeswap/
九、logrotate日志大小限制【不需要可以不装，但是建议，日志管理很重要！】
sudo apt install logrotate
sudo apt install cron
/var/log/syslog
/var/log/mail.log
/var/log/kern.log
/var/log/auth.log
/var/log/user.log
/var/log/cron.log
{
        weekly
rotate 3
        maxsize 100M
        missingok
        notifempty
        compress
        delaycompress
        sharedscripts
        postrotate
                /usr/lib/rsyslog/rsyslog-rotate
        endscript
}

参考文章：
logrotate自定义切割时间的一些坑 - 梦轻尘 - 博客园

Linux日志切割神器logrotate原理介绍和配置详解 | HelloDog

Logrotate 日志滚动 解决日志占用空间过大 - 狐狸的小小窝

Linux 日志管理journald和rsyslog - 星火撩原 - 博客园

https://nj.transwarp.cn:8180/?p=10556
十、Fail2ban 封禁 IP【不需要可以不装】
保护 EC2 实例的开源工具 – Fail2Ban | Amazon Web Services

Protect EC2 instance with Fail2Ban
github.com/fail2ban/fail2ban

Ubunutu用这个
sudo apt install fail2ban

CentOS/RHEL 用这个
sudo yum install epel-release
sudo yum install fail2ban

配置建议 (/etc/fail2ban/jail.local)： 不要直接修改 .conf 文件，新建一个 .local 文件。
sudo nano /etc/fail2ban/jail.local

文本内容：
# 默认设置
[DEFAULT]
ignoreip = 127.0.0.1/8 
# 本地白名单
# SSH servers
[sshd]
enabled = true
backend = systemd
port    = ssh
filter  = sshd 
maxretry = 10           
# 允许失败 10 次
findtime = 300         
# 在 5 分钟内
bantime  = 86400       
# 封禁 1 天 (单位秒)，甚至可以设为 -1 (永久)

启动服务
sudo systemctl restart fail2ban
sudo systemctl enable fail2ban

验证配置 查看当前被封禁的 IP：
sudo fail2ban-client status sshd

十一、面板安装【不需要可以不装】
1panel官网
宝塔面板官网
推荐开源的Linux管理面板——1panel
1panel安装一键脚本
bash -c "$(curl -sSL https://resource.fit2cloud.com/1panel/package/v2/quick_start.sh)"

十二、常规安全更新
安装 unattended-upgrades 来自动更新 security upgrade

通过 unattended-upgrades，可以使 Ubuntu 系统自动进行常规的安全相关更新，使系统一直保持 security。
sudo apt install unattended-upgrades
sudo dpkg-reconfigure unattended-upgrades




openresty
Sat, 29 Nov 2025 00:00:00 GMT
前置准备
安装（已安装则跳过）
1. 安装基础工具
sudo apt-get -y install --no-install-recommends wget gnupg ca-certificates

2. 导入官方签名 (这步是为了安全，必须做)
wget -O - https://openresty.org/package/pubkey.gpg | sudo gpg --dearmor -o /usr/share/keyrings/openresty.gpg

3. 添加仓库
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/openresty.gpg] http://openresty.org/package/ubuntu $(lsb_release -sc) main" | sudo tee /etc/apt/sources.list.d/openresty.list

4. 正式安装
sudo apt-get update
sudo apt-get install openresty -y

确认安装路径:/usr/local/openresty/nginx/
配置目录:/usr/local/openresty/nginx/conf/conf.d/
打开文件：
sudo nano /usr/local/openresty/nginx/conf/nginx.conf


按键盘 Ctrl + V (Page Down) 翻到文件最底部。
找到http的最后一个大括号 }。

在它上面一行插入：
include /usr/local/openresty/nginx/conf/conf.d/*.conf;

这样以后添加配置就只需要进入
/usr/local/openresty/nginx/conf/conf.d/*.conf

保存并退出 (Ctrl+O, Enter, Ctrl+X)。

# 1. 创建存放配置的文件夹
sudo mkdir -p /usr/local/openresty/nginx/conf/conf.d/

# 2. 再次检查配置是否正确
sudo openresty -t

常用命令:
sudo openresty -t (检查),
sudo systemctl reload openresty (重载)
场景一：搭建一个静态网站 (HTML/图片)
这是最基础的用法，用于部署博客、企业官网或前端项目。
1. 准备网页文件 我们先创建一个存放网页的目录（建议放在 /var/www/ 下）：
Bash
sudo mkdir -p /var/www/mywebsite
# 创建一个测试用的 index.html
echo "这是我的静态网站" | sudo tee /var/www/mywebsite/index.html

2. 创建配置文件 新建文件：sudo nano /usr/local/openresty/nginx/conf/conf.d/mywebsite.conf
3. 写入配置
Nginx
server {
    listen 80;
    server_name example.com;  # 将此处改为您的域名或服务器IP

    # 网站根目录
    root /var/www/mywebsite;
    index index.html index.htm;

    # 访问日志（可选，建议开启）
    access_log logs/mywebsite_access.log;
    error_log  logs/mywebsite_error.log;

    location / {
        # 如果找不到文件，尝试返回 index.html (适用于 Vue/React 单页应用)
        try_files $uri $uri/ /index.html;
    }
}

4. 生效
sudo openresty -t   # 检查语法
sudo systemctl reload openresty

现在访问您的域名/IP，就能看到“这是我的静态网站”。
场景二：反向代理 (配合 Python/Go/Node.js)
如果您在服务器上跑了一个 Python (Flask/Django) 或 Go 程序，监听在 127.0.0.1:8000，想通过 OpenResty 暴露给外网。
1. 创建配置文件 新建文件：sudo nano /usr/local/openresty/nginx/conf/conf.d/api_proxy.conf
2. 写入配置
Nginx
server {
    listen 80;
    server_name api.example.com; # 您的 API 域名

    location / {
        # 转发请求到后端的 8000 端口
        proxy_pass http://127.0.0.1:8000;

        # 必须携带的 Header，否则后端拿不到真实 IP
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        
        # 支持 WebSocket (如果需要)
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

若有证书，走443端口，通常已经配置过80到443的强制HTTPS，因此此处省略
server {
    # 1. 必须加上 ssl 关键字
    listen 443 ssl;
    # 2.这里填计划的域名
    server_name openlist.develata.me;

    # 3. 必须复用申请的域名证书
    ssl_certificate      /usr/local/openresty/nginx/conf/ssl/develata.me.crt;
    ssl_certificate_key  /usr/local/openresty/nginx/conf/ssl/develata.me.key;

    # 4. SSL 协议优化 (保持一致性)
    ssl_session_cache    shared:SSL:1m;
    ssl_session_timeout  5m;
    ssl_protocols TLSv1.2 TLSv1.3;

    location / {
        # 转发到其它端口
        proxy_pass http://127.0.0.1:8888;

        # Header 传递
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

        # WebSocket 支持 (如果需要)
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

场景三：利用 Lua 脚本 (OpenResty 独家功能)
这是 OpenResty 最强大的地方，可以在网关层做逻辑处理。例如：简单的 API 鉴权。
1. 创建配置文件 新建文件：sudo nano /usr/local/openresty/nginx/conf/conf.d/lua_auth.conf
2. 写入配置
Nginx
server {
    listen 8090; # 监听 8090 端口测试
    
    location /secret {
        access_by_lua_block {
            -- 获取 URL 参数中的 token
            local token = ngx.var.arg_token
            
            -- 如果 token 不是 '123456'，直接拒绝访问
            if token ~= "123456" then
                ngx.status = 403
                ngx.say("禁止访问：Token 错误或缺失")
                ngx.exit(403)
            end
        }
        
        # 只有通过了上面的 Lua 检查，才会执行下面的内容
        default_type text/html;
        content_by_lua_block {
            ngx.say("欢迎进入机密区域！验证通过。")
        }
    }
}


测试方法：

访问 http://ip:8090/secret -> 被拒绝
访问 http://ip:8090/secret?token=123456 -> 成功



场景四：配置 HTTPS (SSL 证书)
现在网站都需要 HTTPS。我们可以手动配置证书，或者使用 certbot。这里展示标准配置模板。
假设您已经有了证书文件（.crt 和 .key）。
1. 配置文件模板
Nginx
server {
    # 监听443端口的ssl
    listen 443 ssl;
    # 自己域名
    server_name example.com;

    # 证书路径/path/to/your/certificate.crt
    ssl_certificate     /path/to/your/certificate.crt; 
    ssl_certificate_key /path/to/your/private.key;

    # 推荐的安全参数
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;
    # 如果有一个443端口静态页网站，相当于把原本的404换成别的
    # 没有就不需要下面两行
    # root /var/www/mywebsite;
    # index index.html;
}

# HTTP 强制跳转 HTTPS
server {
    listen 80;
    # 自己域名
    server_name example.com;
    # 301永久重定向强制HTTPS
    return 301 https://$host$request_uri;
}

💡 核心排错清单
如果在配置过程中遇到问题，请按此顺序检查：

检查语法： 永远第一步执行 sudo openresty -t。
看日志： 报错原因都在这里：

tail -f /usr/local/openresty/nginx/logs/error.log


检查端口： 确认端口没被占用：

sudo ss -tulpn | grep 80


检查防火墙： 确认服务器防火墙（UFW/iptables）和云服务商的安全组放行了端口。




easytier
Sat, 29 Nov 2025 00:00:00 GMT
官网：https://easytier.cn/
github仓库：https://github.com/EasyTier/EasyTier
Linux一键安装脚本安装
一键脚本依赖 unzip，请提前下载并安装
sudo apt install unzip

安装easytier一键脚本
wget -O /tmp/easytier.sh "https://raw.githubusercontent.com/EasyTier/EasyTier/main/script/install.sh" && sudo bash /tmp/easytier.sh install --gh-proxy https://ghfast.top/

脚本执行成功后，EasyTier 的二进程程序会安装到 /opt/easytier 目录下，配置文件位于 /opt/easytier/config/default.conf。
配置文件可通过 配置文件生成器 生成。
sudo nano /opt/easytier/config/default.conf

一般配置如下
# 当前服务器名
instance_name = "server"
# 当前设备名
hostname = "server"
# 是否开启DHCP，开启则删除ipv4行，false改为true
ipv4 = "10.144.51.1/24"
dhcp = false
# 当前监听端口
listeners = [
    "tcp://0.0.0.0:11010",
    "udp://0.0.0.0:11010",
    # 个人优化，不需要监听wg和wss
    # "wg://0.0.0.0:11011",
    "ws://127.0.0.1:11011/",
    # "wss://0.0.0.0:11012/",
]
# 出口节点列表
exit_nodes = []
# RPC 管理端口
rpc_portal = "0.0.0.0:0"

# 账密
[network_identity]
network_name = "admin"
network_secret = "password"

# 连接目标的域名or网址or ipv4 +端口
# 若为主服务器则不需要填写[[peer]]
# 若需要依次访问多个服务端，那么就填多个[[peer]],url块,不是只添加url
# 注意：IPv6 地址必须用方括号 [] 包起来

# [[peer]]
# uri = "tcp://public.easytier.top:11010"

# 以下为默认配置
[flags]
default_protocol = "udp"
dev_name = "server"
enable_encryption = true
enable_ipv6 = true
mtu = 1380
latency_first = false
enable_exit_node = false
no_tun = false
use_smoltcp = false
foreign_network_whitelist = "*"
disable_p2p = false
p2p_only = false
relay_all_peer_rpc = false
disable_udp_hole_punching = false

防火墙记得放开端口11010
EasyTier 会被注册为系统服务，可以通过以下命令管理：
将 EasyTier 作为后台服务（守护进程）管理
# 启动
sudo systemctl start easytier@default
# 开机自启
sudo systemctl enable easytier@default
# 查看运行状态
sudo systemctl status easytier@default
# 查看详细日志
sudo journalctl -u easytier@default -f
# 停止服务
sudo systemctl stop easytier@default
# 重启
sudo systemctl restart easytier@default

使用 systemctl 可以让 EasyTier 在后台静默运行，并支持开机自启 ，每次修改完配置文件都记得要重启才能生效。
docker-compose
services:
  watchtower: # 用于自动更新easytier镜像，若不需要请删除这部分
    image: m.daocloud.io/docker.io/containrrr/watchtower:latest
    container_name: watchtower
    restart: unless-stopped
    environment:
      - TZ=Asia/Shanghai
      - WATCHTOWER_NO_STARTUP_MESSAGE
      - DOCKER_API_VERSION=1.44
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    command: --interval 3600 --cleanup --label-enable
  easytier:
    image: m.daocloud.io/docker.io/easytier/easytier:latest
    hostname: ali_ecs
    container_name: easytier
    labels:
      com.centurylinklabs.watchtower.enable: 'true'
    restart: unless-stopped
    network_mode: host
    cap_add:
      - NET_ADMIN
      - NET_RAW
    environment:
      - TZ=Asia/Shanghai
    devices:
      - /dev/net/tun:/dev/net/tun
    volumes:
      - /etc/easytier:/root
      - /etc/machine-id:/etc/machine-id:ali_ecs # 映射宿主机机器码
    command: -d --network-name 你的用户名 --network-secret 你的密码 -p tcp://public.easytier.top:11010（官方服务器，-p可填多个，可以换成你自己的） -p 指定你的easytier服务器 -i 指定你的内网ipv4




网络一键脚本搭建(YG)
Sat, 29 Nov 2025 00:00:00 GMT
YG一键脚本github网址：https://github.com/yonggekkk/sing-box-yg
需要sudo权限，建议直接输入sudo -i获取根权限
VPS专用一键脚本如下：快捷方式：sb
bash <(wget -qO- https://raw.githubusercontent.com/yonggekkk/sing-box-yg/main/sb.sh)

或者
bash <(curl -Ls https://raw.githubusercontent.com/yonggekkk/sing-box-yg/main/sb.sh)

Sing-box-yg脚本界面预览图（注：相关参数随意填写，仅供围观）

二、Serv00/Hostuno一键三协议共存脚本（Serv00/Hostuno专用）：

目前免费Serv00使用代理脚本有被封账号的风险，收费版Hostuno不受影响，可正常使用
切勿与其他Serv00脚本混用！！！
引用老王eooce、frankiejun相关功能，支持一键三协议：vless-reality、vmess-ws(argo)、hysteria2
主要增加reality协议默认支持 CF vless/trojan 节点的proxyip以及非标端口的优选反代IP功能
聚合通用节点分享，支持到22个节点：三协议各自三个IP，argo全覆盖13个端口节点，已添加不死优选IP

Serv00/Hostuno-sb-yg一键脚本

Argo高度自定义：可以重置临时隧道; 可以继续使用上回的固定隧道; 也可以更换固定隧道的域名或token

bash <(curl -Ls https://raw.githubusercontent.com/yonggekkk/sing-box-yg/main/serv00.sh)

Serv00/Hostuno-sb-yg脚本界面预览图，仅限方案一的SSH端安装脚本（注：仅供围观）




SSH
Sat, 29 Nov 2025 00:00:00 GMT
1. Tabby - 免费开源（推荐）
👍 优势：

完全免费开源
界面现代化
强大的分屏功能
丰富的插件生态系统
内置SSH客户端、SFTP文件传输
支持PowerShell、CMD、WSL等

👎 劣势：

相对较新，某些高级功能还在完善
内存占用不高，但比PuTTY高，
启动速度不是最快

2. Termius - 多端同步（github教育优惠）
👍 优势：

全平台同步
界面设计精美，用户体验极佳
移动端体验最佳，支持手势操作
免费版功能足够个人使用
支持团队协作（付费功能）

👎 劣势：

高级功能需要付费（同步、团队功能）
相比Tabby功能扩展性稍弱
资源占用相对较高

💡 适用场景：

多设备用户，需要手机端SSH
注重UI/UX体验的用户
简单的个人项目管理

3. PuTTY - 超轻量
👍 优势：

极致轻量，单文件即可运行
启动速度极快，资源占用极低
稳定性经过20+年考验
绿色版，无需安装
支持SSH、Telnet、Serial等多种协议

👎 劣势：

界面老旧，功能单一
不支持多标签（需第三方工具）
配置相对不直观
文件传输需要额外工具(PSFTP)

💡 适用场景：

快速临时连接
低配置电脑使用
应急备用工具
简单的单次连接需求

4. MobaXterm - 全能工具箱
👍 优势：

功能极其全面，一站式解决方案
内置X11服务器，支持图形界面
自带SFTP文件管理器（左右分栏）
集成多种网络工具（端口扫描、网络监控等）
便携版可用，无需安装

👎 劣势：

体积庞大，启动较慢
免费版有会话数量限制
界面相对复杂，学习成本高
主要面向Windows平台

💡 适用场景：

系统管理员、网络工程师
需要多种工具集成的复杂环境
X11转发等高级功能需求
网络故障排查和诊断




acme
Sat, 29 Nov 2025 00:00:00 GMT
前置：
nginx或者openresty
假设你的域名或子域名是 us.example.com
在root账户下创建
1. 安装 acme.sh (轻量级 SSL 签发脚本)
# 这里需要把email换成自己的
curl https://get.acme.sh | sh -s email=my@example.com
source ~/.bashrc

2. 设置 Cloudflare API 变量 (替换为你自己的 Token)
# 不要删除引号，在cloudflare域名-概述页最右下处
export CF_Token="你申请到的CF_Token_字符串"
export CF_Account_ID="你的Cloudflare_Account_ID"

export CF_Token可以自己创建api令牌
3. 申请证书 (替换为你的实际域名)
切换默认 CA 为 Let's Encrypt
~/.acme.sh/acme.sh --set-default-ca --server letsencrypt

# 填自己域名
~/.acme.sh/acme.sh --issue --dns dns_cf -d us.example.com

4. 创建存放证书的目录
openresty:
sudo mkdir -p /usr/local/openresty/nginx/conf/ssl/
# 修改目录权限，把admin改成你当前用户名
sudo chown -R admin:admin /usr/local/openresty/nginx/conf/ssl/

验证：执行 ls -ld /usr/local/openresty/nginx/conf/ssl/，确保显示的是 admin admin。
nginx:
sudo mkdir -p /etc/nginx/ssl/
# 修改目录权限，把admin改成你当前用户名
sudo chown -R admin:admin /etc/nginx/ssl

5. 安装证书到指定位置 (不要直接用生成的路径，要用 install-cert 命令)
openresty：
# 填自己域名
~/.acme.sh/acme.sh --install-cert -d us.example.com \
--key-file       /usr/local/openresty/nginx/conf/ssl/us.example.com.key  \
--fullchain-file /usr/local/openresty/nginx/conf/ssl/us.example.com.crt \
--reloadcmd     "openresty -s reload"

nginx:
~/.acme.sh/acme.sh --install-cert -d us.example.com \
--key-file       /etc/nginx/ssl/us.example.com.key  \
--fullchain-file /etc/nginx/ssl/us.example.com.crt \
--reloadcmd     "systemctl force-reload nginx"

6.查看证书文件
/etc/nginx/ssl/   或者你的 OpenResty 路径
ls -lh /etc/nginx/ssl/

7.查看定时任务
crontab -l

# 填自己域名
~/.acme.sh/acme.sh --install-cert -d *.develata.me \
--key-file       /usr/local/openresty/nginx/conf/ssl/*.develata.me.key  \
--fullchain-file /usr/local/openresty/nginx/conf/ssl/*.develata.me.crt \
--reloadcmd     "openresty -s reload"

8.卸载
openresty：
sudo ~/.acme.sh/acme.sh --uninstall
sudo rm -rf ~/.acme.sh
sudo rm -rf /usr/local/openresty/nginx/conf/ssl/

nginx：
sudo ~/.acme.sh/acme.sh --uninstall
sudo rm -rf ~/.acme.sh
sudo rm -rf /etc/nginx/ssl/

删除定时任务：
检查 root 的定时任务里有没有残留
sudo crontab -u root -l | grep acme 

找到包含 /root/.acme.sh/acme.sh 的那一行，删除。
sudo crontab -u root -e

如果系统跳出来让你选择编辑器（Select an editor），通常会有 nano (推荐新手) 和 vim 等选项。

请输入对应的数字（通常 nano 是 1），然后按回车。




How to Visit the Google Scholar
Thu, 27 Nov 2025 22:43:00 GMT

现状： 在中国大陆，当你直接访问某些境外网站（如 Google、YouTube）时，网络请求经过运营商网关时会被 GFW 识别并拦截（通过 DNS 污染、IP 封锁或 SNI 阻断等方式），导致无法连接。
访问门槛： Google 的所有服务（包括搜索、邮箱、学术、地图）的服务器 IP 地址段在国内大多处于不可达状态。因此，在标准网络环境下，Google 学术是打不开的。

方法一：使用学术镜像站（最简单，免费）
镜像站是原网站的“副本”，通过服务器中转实现访问。这是最快、无需安装任何软件的方法，但缺点是网址经常失效，需要不断寻找新的。

如何寻找：

在百度或必应搜索关键词：“谷歌学术镜像”、“Google Scholar Mirror”。
访问一些专门收集镜像链接的导航站，例如：思谋学术、大木虫学术导航等。


注意事项：

账号安全： 在镜像站上不要登录你的个人 Google 账号。仅用它来搜索和下载文献。
广告： 免费镜像站通常伴有广告，请注意甄别，不要随意点击下载不明插件。



方法二：高校/机构图书馆资源（最正规，最稳定）
如果你是在校大学生或科研机构人员，利用学校购买的资源是最合规且稳定的途径。

WebVPN / 校园网： 许多高校的图书馆网站提供了校外访问系统（WebVPN）。登录后，不仅可以访问 Web of Science、IEEE、Springer 等数据库，有些学校的入口甚至包含谷歌学术的加速通道。
Glgoo (部分高校购买)： Glgoo 也是一个知名的谷歌学术镜像服务，部分高校图书馆会统一购买其服务供学生使用。
直接替代品： 虽然习惯用 Google Scholar，但 Web of Science (WoS) 和 Scopus 在文献引用的权威性上其实更高，且在国内高校网络下通常可以直连。

方法三：浏览器插件/扩展（轻量级，适合轻度用户）
如果你不想折腾复杂的网络设置，可以在浏览器（Chrome 或 Edge）中安装特定的插件。

Edge 浏览器（推荐）：

打开 Edge 的“扩展”商店。
搜索关键词如“谷歌学术助手”、“G助手”、“学术加速”。
安装评价较高的插件。这些插件通常通过代理特定的学术域名来实现访问。


优点： 安装简单，通常只代理学术网站，不影响访问国内网站的速度。
缺点： 很多插件初期免费，后期可能会收费或限速。

方法四：优质的替代搜索引擎（不翻墙的B计划）
当谷歌学术完全无法访问时，以下几个科研搜索引擎是极佳的替代品，甚至在某些功能（如AI分析、关联图谱）上超越了谷歌学术：

Semantic Scholar (语义学者)

特点： 由微软联合创始人保罗·艾伦投资，基于 AI 驱动。它不仅能搜论文，还能分析论文的影响力，提取图表。
访问： 国内通常可直连，速度较快。


AMiner

特点： 清华大学团队研发。对计算机科学（CS）领域的覆盖极佳，拥有强大的专家库和知识图谱。
访问： 完全国内访问，速度极快。


Connected Papers

**特点：**强烈推荐。它不是通过关键词列表展示，而是通过“视觉图谱”展示一篇论文的引文和被引文关系。非常适合做 Literature Review（文献综述）。


X-MOL (化学/生物/材料)

特点： 如果你是生化环材专业，X-MOL 的期刊聚合功能非常强大。



方法五：文献下载神器（配合使用）
谷歌学术主要解决“找”的问题，如果你找到了论文但无法下载（因为没有权限），可以配合以下工具：

Sci-Hub： 学术界的“海盗湾”，通过输入 DOI 号下载全文。域名经常变动，需自行搜索最新域名（如 .se, .ru, .st 等后缀）。
Z-Library： 全球最大的电子书和文献库，虽然主站常被封，但有很多镜像和民间维护的通道。

方法六：科学上网
从技术原理上讲，它主要利用了代理（Proxy）和加密隧道技术。

“科学上网”是目前实现原生、稳定访问 Google 学术的最主要手段。
不仅仅是“打开网页”：

账号同步： 只有通过这种方式，你才能登录 Google 账号，保存你的文献库（My Library），并创建引用提醒。
全文获取： 很多时候，Google 学术提供的 PDF 下载链接也是位于境外的大学或机构服务器，如果不通过代理，下载速度可能极慢或直接中断。
插件联动： 如果你使用 Zotero 或 EndNote 的浏览器插件抓取 Google 学术的元数据，通常也需要代理网络的支持才能正常抓取。


解决方案（搭梯子）：

用户通过特定软件（如 VPN 或代理客户端），将网络请求加密。
加密后的请求发送到一台位于境外的中转服务器。
由于这台境外服务器未被封锁，且数据已加密，GFW 无法识别内容，通常会放行。
境外服务器接收请求后，代替你去访问 Google，并将获取的数据回传给你。


具体步骤

购买一个境外中转服务器
选择SSH工具连接到服务器
学习如何配置服务器






Openlist
Mon, 24 Nov 2025 22:44:00 GMT
见openlist官方快速文档：https://doc.oplist.org.cn/
此处只贴openlist官方快速安装脚本
curl -fsSL https://res.oplist.org/script/v4.sh > install-openlist-v4.sh && sudo bash install-openlist-v4.sh

界面如下
欢迎使用 OpenList 管理脚本

基础功能：
1、安装 OpenList
2、更新 OpenList
3、卸载 OpenList
-------------------
服务管理：
4、查看状态
5、密码管理
6、启动 OpenList
7、停止 OpenList
8、重启 OpenList
-------------------
配置管理：
9、备份配置
10、恢复配置
-------------------
高级选项：
11、Docker 管理
12、定时更新
13、系统状态
14、关于
-------------------
0、退出脚本

根据界面提示，输入1即可安装
如果没有显示脚本界面则输入以下指令进入脚本界面：
sudo openlist

安装完成后，根据界面提示
初始ID：admin
安装完成后，根据脚本界面提示依次输入5和1生成随机密码
然后利用初始ID：admin 和随机密码登入网址127.0.0.1:5244，如果有公网ip就把127.0.0.1换成公网ip
之后进入面板修改账密



大偏差理论
Sun, 23 Nov 2025 23:30:00 GMT
Hello



Linux 原生指令大全 (含语法结构)
Sun, 23 Nov 2025 23:15:00 GMT
Linux 原生指令大全 (含语法结构)

注：此处仅包含 Linux 内核、Coreutils 及 Shell 内建指令，不含第三方应用。

1. 常用原生指令 (高频精简版)



指令
语法结构
描述




ls
ls [选项] [目录]
列出目录内容


cd
cd [目录]
切换工作目录


pwd
pwd
显示当前路径


cp
cp [选项] <源> <目标>
复制文件或目录


mv
mv [选项] <源> <目标>
移动或重命名


rm
rm [选项] <文件/目录>
删除文件或目录


mkdir
mkdir [选项] <目录名>
创建新目录


cat
cat [选项] <文件>
查看或连接文件内容


grep
grep [选项] <模式> <文件>
文本搜索


chmod
chmod [选项] <模式> <文件>
修改文件权限


chown
chown [选项] <用户:组> <文件>
修改文件所有者


ps
ps [选项]
查看进程状态


kill
kill [选项] 
终止进程


ip
ip [选项] <对象> <命令>
网络配置管理


mount
mount -t <类型> <设备> <挂载点>
挂载文件系统


man
man <指令>
查看帮助手册




2. Linux 原生指令全集 (分类速查)
2.1 Shell 内建指令 (Shell Builtins)



指令
语法结构
描述




alias
alias <名称>=<命令>
设置指令别名


bg
bg [作业ID]
将作业放到后台运行


echo
echo [选项] <字符串>
输出字符串


exit
exit [数值]
退出当前 Shell


export
export <变量名>=<值>
设置环境变量


fg
fg [作业ID]
将后台作业提到前台


history
history [行数]
显示历史指令


source
source <文件> 或 . <文件>
在当前 Shell 执行文件


type
type <命令>
显示指令类型


unset
unset <变量/函数>
删除变量或函数



2.2 文件与目录操作 (Coreutils - File)



指令
语法结构
描述




ls
ls [选项] [路径]
列出目录内容


cp
cp [选项] <源> <目标>
复制


mv
mv [选项] <源> <目标>
移动/重命名


rm
rm [选项] <文件>
删除


mkdir
mkdir -p <路径>
创建目录


rmdir
rmdir <目录>
删除空目录


touch
touch <文件>
创建空文件/更新时间戳


ln
ln -s <源文件> <链接名>
创建链接 (软链需加 -s)


readlink
readlink -f <链接>
获取符号链接的真实路径


stat
stat <文件>
显示文件详细状态信息


file
file <文件>
识别文件类型


basename
basename <路径> [后缀]
获取文件名部分


dirname
dirname <路径>
获取目录路径部分



2.3 文本处理与流操作 (Coreutils - Text)



指令
语法结构
描述




cat
cat [文件]
连接并打印内容


tac
tac [文件]
反向打印内容


head
head -n <行数> [文件]
输出开头部分


tail
tail -f [文件]
实时输出结尾部分


more
more [文件]
分页显示


less
less [文件]
高级分页显示


cut
cut -d<分隔符> -f<列> [文件]
按列提取文本


sort
sort [选项] [文件]
排序


uniq
uniq [选项] [文件]
去除相邻重复行


wc
wc -lwn [文件]
统计行/词/字节数


tr
tr <字符集1> <字符集2>
替换或删除字符


tee
command | tee <文件>
双向重定向 (屏幕+文件)


grep
grep -r <文本> <路径>
递归搜索文本


sed
sed 's/旧/新/g' <文件>
流编辑器


awk
awk '{print $1}' <文件>
文本分析工具



2.4 用户、权限与组 (User & Permissions)



指令
语法结构
描述




chmod
chmod <755|+x> <文件>
改变权限


chown
chown <用户>:<组> <文件>
改变所有者


umask
umask [模式]
设置新建文件的默认权限掩码


id
id [用户]
显示用户ID信息


who
who
显示已登录用户


w
w
显示用户及活动


su
su - [用户]
切换用户身份


passwd
passwd [用户]
修改密码


useradd
useradd [选项] <用户>
创建新用户 (底层)


userdel
userdel -r <用户>
删除用户


groupadd
groupadd <组名>
创建新组



2.5 进程管理 (Process)



指令
语法结构
描述




ps
ps aux
进程快照


top
top
实时进程监控


kill
kill -9 
发送信号 (强制杀死)


pkill
pkill <进程名>
按名称杀死进程


nice
nice -n <值> <命令>
设置进程优先级运行


nohup
nohup <命令> &
后台运行且忽略挂起信号


watch
watch -n <秒> <命令>
周期性执行命令



2.6 系统信息与内核 (System & Kernel)



指令
语法结构
描述




uname
uname -a
显示内核系统信息


dmesg
dmesg | grep <关键词>
查看内核环形缓冲日志


uptime
uptime
显示负载和运行时间


date
date "+%Y-%m-%d"
显示/设置时间


free
free -h
查看内存使用情况


lscpu
lscpu
查看CPU架构详情


reboot
reboot
重启系统



2.7 磁盘与文件系统 (Storage)



指令
语法结构
描述




df
df -h
查看磁盘空间


du
du -sh <目录>
查看目录占用大小


lsblk
lsblk
列出块设备


mount
mount <设备> <挂载点>
挂载


umount
umount <挂载点>
卸载


fdisk
fdisk <设备>
磁盘分区工具


mkfs
mkfs.ext4 <设备>
格式化文件系统


sync
sync
强制刷写缓存到磁盘



2.8 网络基础 (Network - iproute2)



指令
语法结构
描述




ip
ip addr show
显示IP地址


ip
ip route show
显示路由表


ip
ip link set <设备> up
启用网卡


ss
ss -tuln
查看监听端口


ping
ping 
测试连通性







Debian 12 指令大全
Sun, 23 Nov 2025 23:15:00 GMT
Debian 12 (Bookworm) 指令大全
1. 常用核心指令 (高频精简版)



指令
语法结构
描述




apt update
apt update
更新软件包索引 (安装前必做)


apt upgrade
apt upgrade
升级所有已安装的软件包


apt install
apt install <包名>
安装新的软件包


apt remove
apt remove <包名>
卸载软件 (保留配置文件)


systemctl
systemctl status <服务>
查看服务运行状态


journalctl
journalctl -xe
查看最近的系统错误日志


ip addr
ip addr
查看网卡与IP地址


ss
ss -tuln
查看正在监听的端口


su
su -
切换到 Root 用户环境


nano
nano <文件>
编辑文本文件 (Debian 默认安装)




2. Debian 12 全面指令 (分类速查)
2.1 高级包管理 (APT - Advanced Package Tool)
Debian 软件包管理的核心前端。



指令
语法结构
描述




apt update
apt update
同步 /etc/apt/sources.list 中的源


apt upgrade
apt upgrade
安全升级软件包 (不删除现有包)


apt full-upgrade
apt full-upgrade
全面升级 (可能移除冲突包以解决依赖)


apt install
apt install <包名>
安装软件包


apt reinstall
apt reinstall <包名>
重新安装 (修复文件损坏)


apt remove
apt remove <包名>
卸载软件


apt purge
apt purge <包名>
彻底卸载 (同时删除配置文件)


apt autoremove
apt autoremove
自动清理不再被依赖的库文件


apt search
apt search <关键词>
搜索软件源中的包


apt show
apt show <包名>
显示软件包详细信息


apt list
apt list --installed
列出已安装的包


apt edit-sources
apt edit-sources
编辑软件源配置文件



2.2 底层包管理 (DPKG)
用于管理本地 .deb 文件及配置。



指令
语法结构
描述




dpkg -i
dpkg -i <文件.deb>
安装本地软件包


dpkg -r
dpkg -r <包名>
移除软件包


dpkg -l
dpkg -l [关键词]
列出系统内已安装的包


dpkg -L
dpkg -L <包名>
查看软件包安装了哪些文件


dpkg -S
dpkg -S <文件路径>
反查文件属于哪个软件包


dpkg-reconfigure
dpkg-reconfigure <包名>
重新配置已安装的包 (Debian 特色)



2.3 系统服务管理 (Systemd)
Debian 12 的初始化系统。



指令
语法结构
描述




systemctl start
systemctl start <服务>
启动服务


systemctl stop
systemctl stop <服务>
停止服务


systemctl restart
systemctl restart <服务>
重启服务


systemctl reload
systemctl reload <服务>
重载配置 (不中断连接)


systemctl status
systemctl status <服务>
查看状态


systemctl enable
systemctl enable <服务>
设置开机自启


systemctl disable
systemctl disable <服务>
禁止开机自启


systemctl mask
systemctl mask <服务>
彻底注销服务 (防止被唤醒)



2.4 日志与时间管理 (System Specifics)



指令
语法结构
描述




journalctl
journalctl -u <服务>
查看指定服务的日志


journalctl
journalctl -f
实时滚动查看最新日志


journalctl
journalctl --vacuum-time=7d
清理7天前的日志


timedatectl
timedatectl set-timezone <时区>
设置系统时区 (如 Asia/Shanghai)


localectl
localectl set-locale LANG=<语言>
设置系统语言环境


hostnamectl
hostnamectl set-hostname <名字>
修改主机名



2.5 网络管理 (IPRoute2)
Debian 12 默认不包含 ifconfig/netstat，推荐使用以下指令。



指令
语法结构
描述




ip addr
ip addr show
显示 IP 地址


ip link
ip link set <网卡> up/down
启用/禁用网卡


ip route
ip route show
显示路由表


ip neigh
ip neigh
显示 ARP 缓存表


ss
ss -tuln
查看 TCP/UDP 监听端口


ss
ss -ta
查看所有建立的 TCP 连接



2.6 用户与权限 (User & Group)
包含 Debian 专有的友好脚本封装。



指令
语法结构
描述




adduser
adduser <用户名>
交互式创建用户 (推荐)


deluser
deluser --remove-home <用户>
删除用户及主目录


addgroup
addgroup <组名>
创建用户组


usermod
usermod -aG <组> <用户>
将用户加入组 (如 sudo 组)


passwd
passwd <用户>
修改密码


visudo
visudo
安全编辑 /etc/sudoers



2.7 辅助工具与系统配置 (Helpers)



指令
语法结构
描述




tasksel
tasksel
菜单化安装常见环境 (桌面/Web服务)


update-alternatives
update-alternatives --config <命令>
切换软件默认版本 (如 Python/Java)


man
man <命令>
查看详细手册


nft
nft list ruleset
查看 nftables 防火墙规则 (原生)


shutdown
shutdown -h now
立即关机


reboot
reboot
重启系统






Debian 12 原生指令补全
Sun, 23 Nov 2025 23:15:00 GMT
Debian 12 原生指令补全

注：此处仅包含Debian12与Linux原生相比的差异指令，不含第三方应用。

Debian 12 专属指令 (Base System)
这些是 Debian 基础系统中特有的核心管理指令。



指令
语法结构
描述




apt
apt install <包名>
现代化包管理 (安装)


apt
apt update
刷新软件源列表


apt
apt purge <包名>
彻底卸载 (含配置)


dpkg
dpkg -i <文件.deb>
安装本地包文件


systemctl
systemctl start <服务>
启动系统服务


systemctl
systemctl enable <服务>
设置开机自启


journalctl
journalctl -u <服务>
查看特定服务日志


adduser
adduser <用户名>
交互式添加用户 (Debian 脚本)


tasksel
tasksel
菜单化选择任务集


dpkg-reconfigure
dpkg-reconfigure <包名>
重新配置已安装软件




⚠️ Debian 12 中“失效/变更”的 Linux 指令
在 Debian 12 (Bookworm) 最小化安装中，以下传统指令可能无法使用。



传统 Linux 指令
Debian 12 现状
替代/新指令语法




ifconfig
被弃用 (未安装)
ip addr


netstat
被弃用 (未安装)
ss -tuln (查看端口)


route
被弃用 (未安装)
ip route


pip
被限制 (PEP 668)
apt install python3-<库> 或 python3 -m venv <目录>


syslog (文件)
不存在 (rsyslog 缺省)
journalctl (直接查看日志库)


scp
协议变更 (SFTP)
scp -O <源> <目标> (若需强制旧协议)


rc.local
不自动运行
需编写 systemd 服务单元






Ubuntu 22.04 LTS 指令大全
Sun, 23 Nov 2025 23:15:00 GMT
Ubuntu 22.04 LTS 指令大全
1. 常用核心指令 (高频精简版)



指令
语法结构
描述




sudo
sudo <命令>
以管理员权限执行命令


apt update
sudo apt update
更新软件源索引


apt upgrade
sudo apt upgrade
升级已安装的软件包


snap install
sudo snap install <包名>
安装 Snap 应用 (Ubuntu 特色)


ufw
sudo ufw allow <端口>
开放防火墙端口


netplan
sudo netplan apply
应用网络配置更改


systemctl
sudo systemctl restart <服务>
重启系统服务


ip addr
ip addr
查看 IP 地址


ssh
ssh <用户>@
远程登录


reboot
sudo reboot
重启系统




2. Ubuntu 22.04 全面指令 (分类速查)
2.1 高级包管理 (APT & PPA)
Ubuntu 的传统包管理，支持 PPA 第三方源。



指令
语法结构
描述




apt update
sudo apt update
刷新软件源列表


apt upgrade
sudo apt upgrade
升级所有软件包


apt install
sudo apt install <包名>
安装软件包


apt remove
sudo apt remove <包名>
卸载软件 (保留配置)


apt purge
sudo apt purge <包名>
彻底卸载 (删除配置)


apt autoremove
sudo apt autoremove
清理无用的依赖包


apt search
apt search <关键词>
搜索软件包


add-apt-repository
sudo add-apt-repository 
添加第三方 PPA 仓库


add-apt-repository
sudo add-apt-repository -r 
移除 PPA 仓库


apt-mark hold
sudo apt-mark hold <包名>
锁定版本禁止自动升级



2.2 Snap 包管理 (Snap Store)
Ubuntu 核心集成的容器化包管理系统。



指令
语法结构
描述




snap install
sudo snap install <包名>
安装应用


snap install
sudo snap install <包> --classic
安装需要经典模式权限的应用


snap remove
sudo snap remove <包名>
卸载应用


snap refresh
sudo snap refresh
更新所有 Snap 应用


snap list
snap list
列出已安装的 Snap 应用


snap find
snap find <关键词>
搜索商店中的应用


snap revert
sudo snap revert <包名>
回滚应用到上一个版本


snap services
snap services
查看 Snap 应用的服务状态



2.3 网络配置 (Netplan)
Ubuntu 18.04+ 标准的声明式网络配置工具。



指令
语法结构
描述




netplan apply
sudo netplan apply
应用配置 (无需重启)


netplan try
sudo netplan try
尝试配置，失败自动回滚 (安全)


netplan generate
sudo netplan generate
生成后端配置文件


netplan ip
netplan ip leases <接口>
查看 DHCP 租约详情


ip addr
ip addr show
查看当前 IP 配置


resolvectl
resolvectl status
查看 DNS 解析状态



2.4 防火墙管理 (UFW)
Ubuntu 默认预装的简易防火墙配置工具。



指令
语法结构
描述




ufw enable
sudo ufw enable
启用防火墙


ufw disable
sudo ufw disable
禁用防火墙


ufw allow
sudo ufw allow <端口/服务>
允许入站连接 (如 22/tcp)


ufw deny
sudo ufw deny <端口>
拒绝入站连接


ufw delete
sudo ufw delete allow <端口>
删除某条规则


ufw status
sudo ufw status numbered
查看带编号的状态列表


ufw reload
sudo ufw reload
重载防火墙配置



2.5 驱动与硬件管理 (Hardware)
Ubuntu 特有的硬件支持工具。



指令
语法结构
描述




ubuntu-drivers
ubuntu-drivers devices
列出建议的专有驱动


ubuntu-drivers
ubuntu-drivers autoinstall
自动安装推荐驱动


lshw
sudo lshw -short
查看硬件列表简报


lsusb
lsusb
查看 USB 设备


lspci
lspci
查看 PCI 设备 (显卡/网卡)



2.6 系统维护与更新 (System Maint)



指令
语法结构
描述




do-release-upgrade
sudo do-release-upgrade
升级到新版 Ubuntu (如 22.04->24.04)


pro
sudo pro attach 
启用 Ubuntu Pro (ESM 更新)


lsb_release
lsb_release -a
查看系统版本详情


shutdown
sudo shutdown -h now
立即关机


reboot
sudo reboot
重启系统



2.7 服务管理 (Systemd)



指令
语法结构
描述




systemctl start
sudo systemctl start <服务>
启动服务


systemctl stop
sudo systemctl stop <服务>
停止服务


systemctl restart
sudo systemctl restart <服务>
重启服务


systemctl enable
sudo systemctl enable <服务>
开机自启


systemctl status
systemctl status <服务>
查看运行状态


journalctl
journalctl -u <服务> -f
实时查看服务日志






Ubuntu 22.04 LTS 独有指令集
Sun, 23 Nov 2025 23:15:00 GMT
Ubuntu 22.04 LTS 独有指令集

注：此处重点列出 Ubuntu 22.04 引入的、区别于 Debian 12 和原生 Linux 内核的特色管理指令。

1. Ubuntu 核心专属指令 (Unique Ecosystem)
这些指令构成了 Ubuntu 区别于其他 Linux 发行版（尤其是 Debian）的核心体验。
1.1 Snap 包管理 (Containerized Packages)
Ubuntu 强推的通用包格式，与系统隔离，包含依赖。Debian 默认不预装 Snap。



指令
语法结构
描述
与 Debian/Linux 差异




snap install
snap install <包名> [--classic]
安装应用 (支持沙盒/经典模式)
独有。Debian 使用 apt 或 flatpak。


snap refresh
snap refresh
更新所有 Snap 应用
独有。独立于 APT 更新机制。


snap list
snap list
列出已安装的 Snap 应用
独有。


snap revert
snap revert <包名>
回滚应用到上个版本
独有。原生 Linux 无此一键回滚功能。


snap switch
snap switch --channel=<分支> <包>
切换软件通道 (stable/beta/edge)
独有。方便尝鲜开发版。



1.2 网络配置 (Netplan)
Ubuntu 17.10+ 开始引入的声明式网络配置工具，取代了传统的 ifupdown。



指令
语法结构
描述
与 Debian/Linux 差异




netplan apply
netplan apply
应用 YAML 配置文件
差异。Debian 默认读取 /etc/network/interfaces。


netplan try
netplan try
尝试配置，失败自动回滚
独有。防止配置错误导致失联的安全机制。


netplan ip
netplan ip leases <接口>
查看 DHCP 租约信息
差异。替代了 dhclient 的查看方式。



1.3 驱动与硬件 (Hardware Enablement)
Ubuntu 特有的硬件驱动自动化管理工具。



指令
语法结构
描述
与 Debian/Linux 差异




ubuntu-drivers
ubuntu-drivers devices
识别硬件并推荐驱动
独有。Debian 需手动修改源并查找驱动包。


ubuntu-drivers
ubuntu-drivers autoinstall
自动安装推荐的闭源驱动
独有。极大简化了显卡/网卡驱动安装。


hwe-support
hwe-support-status
检查硬件启用(HWE)内核状态
独有。针对 LTS 版特供的新内核支持检测。



1.4 系统维护与服务 (Maintenance)
Ubuntu 商业化及易用性工具。



指令
语法结构
描述
与 Debian/Linux 差异




do-release-upgrade
do-release-upgrade
升级到下一个发行版
差异。Debian 用户通常手动修改 sources.list。


add-apt-repository
add-apt-repository ppa:<用户>/<库>
添加 PPA 软件源
差异。Debian 虽可安装此工具，但官方不通过 PPA 分发软件。


pro (旧称 ua)
pro attach 
启用 Ubuntu Pro 服务
独有。用于获取 ESM (扩展安全维护) 和实时内核补丁。


pro
pro status
查看订阅服务状态
独有。




2. ⚡️ 差异对照表：Ubuntu 22.04 vs Debian 12 vs 原生 Linux
这是你需要重点关注的部分，展示了在 Ubuntu 中必须改变的操作习惯。



功能场景
Ubuntu 22.04 LTS 指令
Debian 12 指令
原生 Linux / 旧习惯
差异说明




网络配置生效
netplan apply
systemctl restart networking 
 或 ifup <接口>
service network restart
Ubuntu 配置文件是 YAML 格式，Debian 是文本格式。


安装显卡驱动
ubuntu-drivers autoinstall
apt install nvidia-driver 
 (需先改源开启 non-free)
手动编译或下载 .run 文件
Ubuntu 全自动；Debian 半手动且严格区分自由软件。


跨版本升级
do-release-upgrade
修改 /etc/apt/sources.list 
 然后 apt full-upgrade
无统一标准
Ubuntu 封装了升级脚本，更安全。


防火墙
ufw enable (默认预装)
nft (原生) 或需手装 ufw
iptables (旧) / nftables
Ubuntu 默认使用 UFW 简化防火墙，Debian 偏向底层 nftables。


Root 权限
sudo <命令> (默认)
su - (默认)
su
Ubuntu 默认禁用 root 账户登录，强制 sudo；Debian 安装时可选。


软件源管理
add-apt-repository
手动编辑 /etc/apt/sources.list
无
Ubuntu 依赖 Launchpad PPA 生态。


系统日志
journalctl (主要) 
 保留了 /var/log/syslog
journalctl (唯一) 
 删除了 /var/log/syslog
syslogd
Ubuntu 22.04 仍保留了文本日志文件兼容旧习，Debian 12 默认已删除。


Python 环境
python3 (受 PEP 668 限制)
python3 (受 PEP 668 限制)
pip install
两者都限制了直接用 pip 安装全局包，必须用 apt 或 venv。

工具	配置文件路径	说明
Claude Code	`~/.claude/settings.json` / `~/.claude.json`	存储配置、认证与 MCP
Codex	`~/.codex/auth.json`	存储认证信息
Codex	`~/.codex/config.toml`	存储 MCP Server
Gemini CLI	`~/.gemini/.env`	存储 API Key
Gemini CLI	`~/.gemini/settings.json`	存储认证模式和 MCP

变量	用途
`ANTHROPIC_API_KEY`	API Key（`X-Api-Key`）
`ANTHROPIC_AUTH_TOKEN`	Bearer token（`Authorization`）
`ANTHROPIC_MODEL`	默认模型（alias 或 model name）
`ANTHROPIC_BASE_URL`	LLM gateway / 代理 base URL（Anthropic Messages 格式）
`ANTHROPIC_DEFAULT_OPUS_MODEL`	覆盖 `opus` 的默认模型名
`ANTHROPIC_DEFAULT_SONNET_MODEL`	覆盖 `sonnet` 的默认模型名
`ANTHROPIC_DEFAULT_HAIKU_MODEL`	覆盖 `haiku` 的默认模型名（`ANTHROPIC_SMALL_FAST_MODEL` 已 deprecated）
`ANTHROPIC_CUSTOM_HEADERS`	给所有请求追加自定义 HTTP header
`HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY`	代理配置
`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1`	同时关闭自动更新/遥测/错误上报等非必要流量
`NODE_EXTRA_CA_CERTS`	追加企业 CA 证书（代理/网关环境常用）
`CLAUDE_CODE_CLIENT_CERT` / `CLAUDE_CODE_CLIENT_KEY`	mTLS 客户端证书/私钥
`DISABLE_AUTOUPDATER=1`	关闭自动更新
`CLAUDE_CONFIG_DIR`	自定义配置与数据目录
`MCP_TIMEOUT` / `MCP_TOOL_TIMEOUT`	MCP 启动/执行超时（ms）
`MAX_MCP_OUTPUT_TOKENS`	MCP 输出 token 上限
`ENABLE_TOOL_SEARCH`	MCP tool search（`auto`/`auto:N`/`true`/`false`）
`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1`	禁用后台任务
`CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION=false`	关闭输入框提示补全
`BASH_DEFAULT_TIMEOUT_MS` / `BASH_MAX_TIMEOUT_MS`	Bash 默认/最大超时（ms）

Agent	主要职责	默认模型	Tools（声明）	常见入口
`planner`	复杂需求拆解为可执行计划，并等待确认	`opus`	`Read,Grep,Glob`	`/plan`
`architect`	架构设计与技术决策（边界、扩展性、风险）	`opus`	`Read,Grep,Glob`	（手动委托/复杂方案评审）
`tdd-guide`	强制 TDD（先测后码、覆盖率目标）	`opus`	`Read,Write,Edit,Bash,Grep`	`/tdd`
`code-reviewer`	质量 + 安全 + 可维护性审查	`opus`	`Read,Grep,Glob,Bash`	`/code-review`
`security-reviewer`	安全漏洞检测与修复建议	`opus`	`Read,Write,Edit,Bash,Grep,Glob`	（敏感改动后）
`build-error-resolver`	修 build/TS 错误，最小 diff 快速变绿	`opus`	`Read,Write,Edit,Bash,Grep,Glob`	`/build-fix`
`e2e-runner`	Playwright E2E（含 flaky 隔离与 artifacts）	`opus`	`Read,Write,Edit,Bash,Grep,Glob`	`/e2e`
`refactor-cleaner`	死代码识别与清理（分析→验证→删除）	`opus`	`Read,Write,Edit,Bash,Grep,Glob`	`/refactor-clean`
`doc-updater`	文档/codemap 同步与生成	`opus`	`Read,Write,Edit,Bash,Grep,Glob`	`/update-docs`、`/update-codemaps`
`go-reviewer`	Go 代码审查（惯用法/并发/错误处理/性能）	`opus`	`Read,Grep,Glob,Bash`	`/go-review`
`go-build-resolver`	Go build/vet/lint 修复（最小改动）	`opus`	`Read,Write,Edit,Bash,Grep,Glob`	`/go-build`
`python-reviewer`	Python 审查（PEP8/类型标注/安全/性能）	`opus`	`Read,Grep,Glob,Bash`	`/python-review`
`database-reviewer`	PostgreSQL/Supabase（schema/index/query/security/perf）	`opus`	`Read,Write,Edit,Bash,Grep,Glob`	（SQL/migration/慢查询时）

Agent	推荐模型（默认/备选）
Sisyphus	`claude-opus-4-6`（Fallback：`gpt-5.3-codex` → deep quality chain）
Hephaestus	`gpt-5.3-codex`（Fallback：deep quality chain：`claude-opus-4-6-thinking` → `step-3.5-flash` → `glm-5` → …）
Oracle	`gpt-5.3-codex`（Fallback：`claude-opus-4-6-thinking` → `claude-sonnet-4-5-thinking` → deep quality chain）
Librarian	`claude-sonnet-4-5`（Fallback：speed chain：`claude-haiku-4-5` → `gpt-5-mini` → … → quality chain）
Explore	`claude-haiku-4-5`（Fallback：`oswe-vscode-prime` → `gpt-5-mini` → `gpt-4.1` → extended speed chain）
Multimodal-Looker	`gemini-3-pro-image`（Fallback：`gemini-3-pro-high` → `gemini-3-flash` → `kimi-k2.5` → `claude-opus-4-6-thinking` → `claude-sonnet-4-5-thinking` → `claude-haiku-4-5` → `gpt-5-nano`）
Prometheus	`claude-opus-4-6-thinking`（Fallback：`gpt-5.3-codex` → `claude-sonnet-4-5-thinking` → deep quality chain）
Metis	`claude-opus-4-6-thinking`（Fallback：`gpt-5.3-codex` → `claude-sonnet-4-5-thinking` → deep quality chain）
Momus	`gpt-5.3-codex`（Fallback：`claude-opus-4-6-thinking` → deep quality chain）
Atlas	`claude-sonnet-4-5-thinking`（Fallback：`claude-opus-4-6-thinking` → `gpt-5.3-codex` → deep quality chain）
Sisyphus-Junior	(category-dependent)（随 category 自动选模型）

Category	默认模型	典型用途
`visual-engineering`	`google/gemini-3-pro`	前端 / UI/UX / 动效 / 视觉实现
`ultrabrain`	`openai/gpt-5.3-codex`（xhigh）	极深推理、复杂架构决策
`deep`	`openai/gpt-5.3-codex`（medium）	“深度模式”自主问题解决
`artistry`	`google/gemini-3-pro`（max）	创意/审美/新颖方案
`quick`	`anthropic/claude-haiku-4-5`	小修小补、低成本快速改动
`unspecified-low`	`anthropic/claude-sonnet-4-6`	通用低难任务
`unspecified-high`	`anthropic/claude-opus-4-6`（max）	通用高难任务
`writing`	`kimi-for-coding/k2p5`	文档、说明、技术写作

Scope	文件	说明
User	`~/.claude/settings.json`	个人全局设置
Project	`.claude/settings.json`	团队共享（建议提交 git）
Local	`.claude/settings.local.json`	个人覆盖（通常 gitignore）
Managed	`managed-settings.json`	组织级强制策略（系统目录下发）

快捷键	功能	快捷键	功能
Ctrl+x n	开启新会话	Ctrl+x u	撤销修改
Ctrl+x l	列出历史会话	Ctrl+x r	重做修改
Ctrl+x m	切换模型	Ctrl+x s	分享会话
Ctrl+x i	初始化项目	Ctrl+x e	外部编辑器
Ctrl+x t	切换主题	Ctrl+x q	退出
Ctrl+x b	切换侧边栏	Ctrl+x y	复制消息
Ctrl+x a	Agent 列表	Ctrl+x g	会话时间线

命令	主要作用	主要调用	参数/备注
`/plan`	产出分阶段实施计划并等待确认	agent: `planner`	命令文档强调“未确认不得改代码”
`/tdd`	强制 TDD：先测试→最小实现→重构→覆盖率	agent: `tdd-guide`	覆盖率目标 80%+；E2E 另用 `/e2e`
`/code-review`	未提交变更的安全与质量审查	workflow（检查清单）	输出按 CRITICAL/HIGH/MEDIUM/LOW；CRITICAL/HIGH 应阻断提交
`/verify`	验证闭环（build/types/lint/tests/日志审计/git 状态）	workflow	支持 `quick/full/pre-commit/pre-pr`
`/build-fix`	增量修 build/类型错误（一次只修一个）	workflow	每次修复后重跑 build；同一错误多次失败应停下
`/test-coverage`	分析覆盖率并补齐缺失测试	workflow	常与 `/tdd`、`/verify` 配合
`/e2e`	生成/维护/执行 Playwright E2E	agent: `e2e-runner`	覆盖关键用户旅程；隔离 flaky tests
`/checkpoint`	创建/核对一个工作流检查点	workflow	用于阶段性确认/复盘
`/eval`	EDD：定义/运行/报告 eval	workflow（配合 `skills/eval-harness`）	适合把“成功标准”先写死
`/learn`	从当前会话提炼可复用模式	workflow（配合 continuous-learning）	更偏人工触发抽取
`/sessions`	会话历史管理（list/load/alias/info）	Node 脚本	读写 `~/.claude/sessions/`、`~/.claude/session-aliases.json`
`/setup-pm`	设置/检测包管理器偏好	Node 脚本	优先级：env→项目→package.json→lock→全局→fallback
`/skill-create`	从 git 历史生成 SKILL.md（可选 instincts）	workflow	`--commits/--output/--instincts`
`/instinct-status`	查看 instincts（置信度/分组）	instinct CLI	continuous-learning-v2 配套
`/instinct-import`	导入 instincts	instinct CLI	continuous-learning-v2 配套
`/instinct-export`	导出 instincts	instinct CLI	continuous-learning-v2 配套
`/evolve`	instincts 聚类进化为技能/命令/代理	instinct CLI	continuous-learning-v2 配套
`/go-review`	Go 专用审查	agent: `go-reviewer`	并发/错误处理/性能/惯用法
`/go-build`	Go build/vet 修复	agent: `go-build-resolver`	最小改动、快速绿灯
`/go-test`	Go 的 TDD/测试套路	workflow	table-driven tests、race、coverage
`/python-review`	Python 专用审查	agent: `python-reviewer`	PEP8、类型标注、安全与性能
`/refactor-clean`	死代码识别与清理	agent: `refactor-cleaner`（概念上）	强调安全删除 + 验证
`/update-docs`	文档同步	agent: `doc-updater`（概念上）	从 source-of-truth 同步
`/update-codemaps`	生成/更新 codemaps	agent: `doc-updater`（概念上）	适合大仓库导航
`/orchestrate`	顺序式多 agent 协作（复杂任务）	workflow	把任务拆阶段推进
`/multi-plan`	多模型协作产计划	workflow	高级用法，依赖额外 wrapper/MCP
`/multi-execute`	多模型协作执行与审计	workflow	高级用法，依赖额外 wrapper/MCP
`/multi-frontend`	偏前端多模型流程	workflow	文档标注“Gemini-led”
`/multi-backend`	偏后端多模型流程	workflow	文档标注“Codex-led”
`/multi-workflow`	全流程多模型协作	workflow	该命令文档的 usage 写成 `/workflow ...`；以文件名映射的命令 `/multi-workflow` 为准
`/pm2`	多服务 PM2 初始化与命令生成	workflow	生成 `ecosystem.config.cjs` 与 `.claude/commands/pm2-*.md`

命令/触发	类型	用途	最小用法	常见误用
`ulw` / `ultrawork`	关键词	自动化冲刺执行	`修复 X 并补测，ulw`	把它当 slash 命令
`@plan`	prompt	复杂任务先规划	`@plan 重构鉴权模块并保持行为不变`	不给边界与验收
`/init-deep`	slash	新项目接入 OMO	`/init-deep`	不在仓库根（或子目录）执行
`/start-work`	slash	按计划执行闭环	`/start-work`	没有计划就直接执行
`/ulw-loop`	slash	ultrawork + 循环推进	`/ulw-loop "批量修复 lint + type 错误"`	用在小任务上导致过度开销
`/ralph-loop`	slash	长任务持续推进	`/ralph-loop "迁移旧接口到新 SDK"`	目标不清晰就开循环
`/cancel-ralph`	slash	停止 ralph 循环	`/cancel-ralph`	以为会停止所有机制
`/stop-continuation`	slash	停止 continuation 机制	`/stop-continuation`	以为会撤销已完成修改
`/refactor`	slash	结构化重构入口	`/refactor src/auth --strategy=safe`	把功能新增当重构任务
`/handoff`	slash	跨会话交接	`/handoff`	只写一句话，没带上下文

路径	谁生成/谁维护	用途	常见误用
`AGENTS.md`（分层）	`/init-deep` 生成	给 agent 提供“就近上下文约束”，减少上下文污染	以为它会自动更新业务规则
`.opencode/oh-my-opencode.jsonc`	你维护（项目级）	团队共享的 OMO 路由/模型覆盖	提交了本地密钥或私密模型名
`~/.config/opencode/oh-my-opencode.jsonc`	你维护（用户级）	个人偏好覆盖（不影响仓库）	用用户级配置覆盖掉团队约束
`~/.config/opencode/opencode.json`	OpenCode 维护	OpenCode 全局配置；用于确认插件已加载（`oh-my-openagent` / `oh-my-opencode`）	把 OMO 配置写进这里导致难以迁移

代理/类别	核心职责
Sisyphus（总控）	默认总编排器：规划、拆解、并行委派子任务并执行闭环（todo 驱动，强并发）。
Hephaestus（执行）	深度自主实现：复杂调试、架构落地、端到端完成任务（“深度模式/工匠”）。
Oracle（分析推理）	架构决策/代码审查/疑难 Debug 咨询：只读分析，给高质量推理建议。
Librarian（资料库）	多仓库/文档/开源实现检索与对比：证据驱动的解释与定位。
Explore（代码库）	快速扫代码库、grep/上下文定位：为主 Agent 提供“快而准”的线索。
Multimodal-Looker（眼睛）	视觉内容专家：分析 PDF / 图片 / 图表 / 截图提取信息（只读）。
Prometheus（需求访谈）	访谈式规划：通过迭代提问产出可执行的详细计划。
Metis（规划）	计划顾问（pre-planning）：挖掘隐藏意图、歧义、潜在失败点。
Momus（挑刺）	计划审稿人：按清晰度/可验证性/完整性标准“挑刺”与校验。
Atlas（团队管理）	todo-list 执行编排：按计划逐项推进、管理 todo 并协调执行（自身不再委派）。
Sisyphus-Junior（临时工）	被 `task(category=...)` 生成的执行体：模型随 category 自动选择；禁止再次委派，防止无限递归。

路径	生成来源	你用它做什么（建议亲自审一遍）	下一步
`spec.md`	`/speckit.specify`	写清用户故事（含优先级 P1/P2/P3）、验收场景（Given/When/Then）、边界条件（Edge Cases）、需求（FR-xxx）、成功标准（SC-xxx）	把 “NEEDS CLARIFICATION” 清零后再做 plan
`plan.md`	`/speckit.plan`	实现路线图：技术上下文、门禁（Constitution Check）、项目结构选择、复杂度偏离说明、分阶段交付与验证点	以它为准做任务拆解
`research.md`	`/speckit.plan`	Phase 0：把 `spec.md` 里的不确定项逐条补齐（尤其是 “NEEDS CLARIFICATION”）	结论要回写到 plan/contracts/data-model
`data-model.md`	`/speckit.plan`	Phase 1：把关键实体/字段/关系/约束写成可实现的数据模型	先对齐模型，再写代码与测试
`quickstart.md`	`/speckit.plan`	Phase 1：最短验证路径（命令块 + 成功判据），用于 smoke test/交付演示	实现完成后用它做最后验收
`contracts/`	`/speckit.plan`	Phase 1：接口契约（例如 OpenAPI/JSON schema/事件定义），用于契约测试与 mock	契约优先更新，再改实现与测试
`tasks.md`	`/speckit.tasks`	可执行清单：按 User Story 分组；任务带 ID（`T001`…）；`[P]` 可并行；可选 tests（仅 spec 要求时才写）	按任务逐条落地并回填验证结果

位置	用途
`.specify/`	工作区根目录（memory/templates/scripts/extensions 等）
`.specify/memory/constitution.md`	项目“宪法”；若已存在，初始化不会覆盖
`.specify/templates/`	命令模板（例如 `constitution-template.md`）
`.specify/scripts/`	内置脚本（按 `--script sh
`.specify/extensions.yml`	扩展启用清单（YAML）
`.specify/extensions/.registry`	扩展注册表（已安装/启用状态）
`.specify/extensions/.cache/`	扩展与 catalog 缓存目录
`.specify/extensions//`	单个扩展的本地文件与配置
`.specify/extensions//-config.yml`	扩展项目级配置（可选）
`.specify/extensions//local-config.yml`	扩展本地配置（可选，通常不入库）

参数	是否必填	说明
`--ai`	否	选择 AI 工具模板；不传则交互式选择
`--script sh	ps`	否
`--here`	否	将模板写入当前目录（而非创建新目录）
`--force`	否	跳过覆盖/危险操作确认
`--no-git`	否	不要求/不依赖 git 分支名推导 feature
`--github-token`	否	GitHub API Token（用于拉取最新模板 release）
`--skip-tls`	否	跳过 TLS 校验（仅排障）
`--debug`	否	打印调试日志
`--ai-commands-dir`	条件必填	仅 `--ai generic` 需要：把命令文件输出到指定目录
`--ai-skills`	否	将 `speckit.*` 安装为 Agent Skills（Prompt.MD）；需要同时指定 `--ai`

变量	是否必填	用途
`GH_TOKEN`	否	GitHub API Token（等价替代 `--github-token`）
`GITHUB_TOKEN`	否	GitHub API Token（等价替代 `--github-token`）
`SPECIFY_FEATURE`	否	覆盖 feature 名推导（脚本/命令会优先用它）
`CODEX_HOME`	否	使用 Codex CLI 时需指向项目内 `.codex/`（示例：`export CODEX_HOME="$PWD/.codex"`）
`SPECKIT__` `_`	否	扩展配置覆盖：会覆盖扩展 YAML 中对应键（会先转为全大写并把 `-` 替换为 `_`）

`--ai` 值	命令目录（项目内）
`claude`	`.claude/commands/`
`codex`	`.codex/prompts/`
`cursor-agent`	`.cursor/commands/`
`gemini`	`.gemini/commands/`
`opencode`	`.opencode/command/`
`copilot`	`.github/agents/`
`windsurf`	`.windsurf/workflows/`
`generic`	由 `--ai-commands-dir` 指定

操作	命令	示例
搜索软件	`brew search`	`brew search python`
查看详情	`brew info`	`brew info node`
安装软件	`brew install`	`brew install wget`
查看已装	`brew list`	`brew list`
检查更新	`brew outdated`	`brew outdated`
更新索引	`brew update`	`brew update`
升级软件	`brew upgrade`	`brew upgrade`
卸载软件	`brew uninstall`	`brew uninstall wget`
清理缓存/旧版本	`brew cleanup`	`brew cleanup`
清理无用依赖	`brew autoremove`	`brew autoremove`

工具	用途	命令
`ripgrep`	极速全文搜索	`brew install ripgrep`
`fd`	更友好的文件搜索	`brew install fd`
`fzf`	模糊查找	`brew install fzf`
`bat`	带高亮的 `cat` 替代品	`brew install bat`
`eza`	更现代的 `ls`	`brew install eza`
`zoxide`	智能目录跳转	`brew install zoxide`
`jq`	JSON 处理	`brew install jq`
`neovim`	现代编辑器	`brew install neovim`

目的	命令
启动默认发行版	`wsl`
启动指定发行版	`wsl -d`
查看已安装发行版	`wsl -l -v`
设置默认发行版	`wsl --set-default`
停止指定发行版	`wsl --terminate`
停止所有发行版	`wsl --shutdown`
更新 WSL 内核	`wsl --update`
导出发行版备份	`wsl --export`
导入发行版	`wsl --import`
卸载发行版	`wsl --unregister`

策略	含义
`Restricted`	不允许运行任何脚本（默认）
`RemoteSigned`	本地脚本可运行；网络下载的脚本需签名
`Unrestricted`	允许所有脚本（不推荐）
`Bypass`	完全绕过，常用于 CI/自动化

目的	命令
列出文件	`Get-ChildItem`（别名 `ls`/`dir`/`gci`）
查看内容	`Get-Content` （别名 `cat`）
复制	`Copy-Item`
移动/重命名	`Move-Item`
删除	`Remove-Item`
查看进程	`Get-Process`
停止进程	`Stop-Process -Name`
查看服务	`Get-Service`
查看环境变量	`$env:PATH`；`Get-ChildItem Env:`
查找命令	`Get-Command`
查看帮助	`Get-Help -Full`
历史记录	`Get-History`；`Ctrl+R` 搜索
测试网络连通性	`Test-Connection` （类似 ping）
DNS 解析	`Resolve-DnsName`
查看网络接口	`Get-NetIPAddress`

模块	用途
`PSReadLine`	命令行编辑增强（Windows PowerShell 5.1 已内置）
`posh-git`	Git 状态提示
`Terminal-Icons`	终端文件图标
`Microsoft.WinGet.Client`	PowerShell 内操作 WinGet

现象	原因 / 解决
`wsl --install` 报错 0x800701bc	WSL 内核未更新，运行 `wsl --update`
发行版启动后立即退出	尝试 `wsl --shutdown` 再重启；或检查 `wsl.conf` 语法
访问 `/mnt/c` 性能慢	将项目迁移到 Linux 文件系统内（`~/`）
网络无法访问	执行 `wsl --shutdown` 重启；或检查 `.wslconfig` 网络设置

指令	语法结构	描述
git init	`git init`	初始化本地仓库
git clone	`git clone <仓库地址>`	克隆远程仓库
git status	`git status`	查看工作区与暂存区状态
git add	`git add <文件>` 或 `git add .`	添加变更到暂存区
git commit	`git commit -m '<说明>'`	提交暂存区到本地仓库
git log	`git log --oneline --graph`	查看提交历史
git diff	`git diff` / `git diff --cached`	查看未暂存/已暂存差异
git branch	`git branch` / `git branch -a`	查看分支
git switch	`git switch <分支>`	切换分支
git merge	`git merge <分支>`	合并分支
git fetch	`git fetch --prune`	拉取远程更新（不自动合并）
git pull	`git pull <远程> <分支>`	拉取并合并
git push	`git push <远程> <分支>`	推送本地提交到远程
git stash	`git stash` / `git stash pop`	临时保存并恢复工作区修改

指令	语法结构	描述
`git init`	`git init`	初始化仓库
`git clone`	`git clone <仓库地址>`	克隆远程仓库
`git config`	`git config --global user.name '<用户名>'`	配置全局用户名
`git config`	`git config --global user.email '<邮箱>'`	配置全局邮箱
`git config`	`git config --global color.ui true`	启用命令输出着色
`git config`	`git config --global --unset http.proxy`	取消 Git 代理
`git remote`	`git remote add origin <仓库地址>`	添加远程仓库别名
`git remote`	`git remote -v`	查看远程仓库地址

指令	语法结构	描述
`git status`	`git status`	查看当前状态
`git add`	`git add <文件>`	暂存指定文件
`git add`	`git add .`	暂存当前目录全部变更
`git commit`	`git commit -m '<说明>'`	创建提交
`git commit`	`git commit -am '<说明>'`	跳过 `add` 提交已跟踪文件
`git commit`	`git commit --amend -m '<说明>'`	修改最近一次提交
`git rm`	`git rm <文件>`	删除文件并记录到暂存区
`git mv`	`git mv <旧名> <新名>`	重命名并记录变更
`git ls-files`	`git ls-files`	查看索引中已跟踪文件

指令	语法结构	描述
`git log`	`git log`	查看完整提交日志
`git log`	`git log -n <数量>`	查看最近 N 条日志
`git log`	`git log --stat`	查看日志及文件统计
`git log`	`git log -p -m`	查看日志及补丁内容
`git log`	`git log --pretty=format:'%h %s' --graph`	图形化简洁日志
`git show`	`git show`	查看指定提交详情
`git show`	`git show HEAD` / `git show HEAD^`	查看当前/父提交
`git diff`	`git diff`	工作区与暂存区差异
`git diff`	`git diff --cached`	暂存区与最近提交差异
`git diff`	`git diff HEAD^`	与上一个提交比较
`git diff`	`git diff HEAD -- <路径>`	与当前提交比较指定路径
`git diff`	`git diff <远程>/<分支>..<本地分支> --stat`	对比分支差异统计
`git grep`	`git grep '<模式>'`	在版本库中搜索文本

指令	语法结构	描述
`git branch`	`git branch`	查看本地分支
`git branch`	`git branch -a` / `git branch -r`	查看全部/远程分支
`git branch`	`git branch --merged`	查看已合并分支
`git branch`	`git branch --no-merged`	查看未合并分支
`git branch`	`git branch --contains`	查找包含指定提交的分支
`git branch`	`git branch -m <旧分支> <新分支>`	重命名分支
`git branch`	`git branch -d <分支>`	删除已合并分支
`git branch`	`git branch -D <分支>`	强制删除分支
`git checkout`	`git checkout -b <新分支>`	基于当前提交新建并切换
`git checkout`	`git checkout -b <本地分支> <远程>/<分支>`	基于远程分支创建本地分支
`git checkout`	`git checkout --track <远程分支>`	创建跟踪分支
`git switch`	`git switch <分支>`	切换到已有分支
`git merge`	`git merge <分支>`	合并指定分支到当前分支
`git cherry-pick`	`git cherry-pick`	摘取单个提交
`git rebase`	`git rebase <目标分支>`	变基整理提交历史

指令	语法结构	描述
`git fetch`	`git fetch`	获取远程更新
`git fetch`	`git fetch --prune`	获取更新并清理远程已删分支
`git pull`	`git pull <远程> <分支>`	拉取并合并到当前分支
`git push`	`git push <远程> <分支>`	推送当前分支
`git push`	`git push --tags`	推送全部标签
`git push`	`git push <远程> :<分支>`	删除远程分支

指令	语法结构	描述
`git tag`	`git tag`	查看标签
`git tag`	`git tag -a <标签> -m '<说明>'`	创建附注标签
`git show`	`git show <标签>`	查看标签详情
`git log`	`git log <标签>`	查看标签对应历史
`git stash`	`git stash`	暂存当前修改
`git stash`	`git stash list`	查看暂存列表
`git stash`	`git stash show -p stash@{<序号>}`	查看某次暂存详情
`git stash`	`git stash apply stash@{<序号>}`	应用某次暂存
`git stash`	`git stash pop`	应用并删除最近暂存

指令	语法结构	描述
`git checkout`	`git checkout -- <文件>`	丢弃工作区指定文件修改
`git reset`	`git reset --hard HEAD`	强制重置到当前提交
`git revert`	`git revert`	反向提交以撤销历史改动
`git reflog`	`git reflog`	查看引用变动历史（含丢失提交）
`git show`	`git show HEAD@{}`	查看 reflog 指定位置
`git show`	`git show <分支>@{yesterday}`	查看分支历史时点状态
`git show`	`git show HEAD~`	查看第 n 个祖先提交
`git show-branch`	`git show-branch --all`	图示所有分支历史
`git whatchanged`	`git whatchanged`	查看提交对应文件变更
`git ls-tree`	`git ls-tree HEAD`	查看树对象内容
`git rev-parse`	`git rev-parse`	解析引用对应的 SHA
`git gc`	`git gc`	压缩清理仓库对象
`git fsck`	`git fsck`	校验仓库对象完整性

目的	命令
搜索	`winget search` （可用 `--id/--name/--tag/--command` 过滤）
详情	`winget show --id`
安装	`winget install --id -e`（推荐：`--id + -e`）
已装	`winget list`
可升级	`winget upgrade`
全量升级	`winget upgrade --all`（可加 `--include-unknown/--include-pinned`）
卸载	`winget uninstall --id -e`
迁移	`winget export` / `winget import`
Source	`winget source list/update`
锁版本	`winget pin add/list/remove`

现象	常见原因	修复
`Cannot bind any address` / `ERROR:10049`	`ListenAddress` 填了网段或不存在 IP	填 EasyTier 主机 IP
`Authentication failed with public key`	公钥位置不对 / 权限不对 / key 粘贴断行	检查管理员组路径 + `icacls`
密码总失败（只有 PIN）	PIN 不是 Windows 密码	用密钥登录；或设置 Windows Password

操作	命令	示例
搜索	`scoop search`	`scoop search python`
搜索	`scoop search`	显示所有支持的软件
安装	`scoop install`	`scoop install vscode`
更新	`scoop update *`	更新所有软件
清理	`scoop cleanup *`	删除旧版本安装包
状态	`scoop status`	检查是否有更新

工具	用途	命令
ripgrep	极速代码搜索 (比 grep 快得多)	`scoop install ripgrep`
fd	极速文件搜索 (比 find 友好)	`scoop install fd`
fzf	模糊查找神器	`scoop install fzf`
bat	带语法高亮的 cat 替代品	`scoop install bat`
neovim	现代化 Vim 编辑器	`scoop install neovim`
7zip	命令行解压工具	`scoop install 7zip`
ffmpeg	视音频处理瑞士军刀	`scoop install ffmpeg`

Name	Secret (Value) 填什么？
`ALIYUN_USERNAME`	你的阿里云全名（在 ACR“访问凭证”页可以看到，通常是 `用户名@账号ID` 这种格式）
`ALIYUN_PASSWORD`	刚才在 ACR 里设置的那个“固定密码”
`ALIYUN_NAMESPACE`	刚才创建的命名空间名字（例如 `my-docker-hub` ）
`ALIYUN_REGISTRY`	你的 ACR 公网地址（在 ACR“概览”页可以看到，例如 `registry.cn-hangzhou.aliyuncs.com` ）

类型	限制/额度	评价
公开包 (Public)	完全免费，无限制	⭐⭐⭐⭐⭐
私有包 (Private)	500 MB (免费版)	❌ ****
	2 GB (Pro 版)	勉强够用

指令	描述	常用示例
ufw enable	启用防火墙 (开机自启)	`sudo ufw enable`
ufw disable	禁用防火墙	`sudo ufw disable`
ufw status	查看状态及规则	`sudo ufw status`
ufw reload	重载配置 (不中断连接)	`sudo ufw reload`
ufw allow	允许外部访问端口	`sudo ufw allow 22/tcp` (开放 SSH)
ufw deny	拒绝外部访问端口	`sudo ufw deny 80`
ufw delete	删除某条规则	`sudo ufw delete allow 22`
ufw reset	重置所有规则至默认	`sudo ufw reset` (慎用，需重新配置)

指令	描述
`ufw enable`	开启防火墙 (默认策略：拒绝入站，允许出站)
`ufw disable`	关闭防火墙
`ufw reload`	重新加载配置文件
`ufw reset`	重置防火墙配置为默认状态 (会清空所有自定义规则)
`ufw status`	显示防火墙状态和当前激活的规则
`ufw status verbose`	显示详细状态 (包括默认策略、日志级别)
`ufw status numbered`	显示带编号的规则列表 (常用于删除指定规则)