2026-04-15 13:44:00

Claude Code 可以通过 -p 标志、权限绕过、循环模式和终端持久化的组合，实现数小时甚至整夜的无人值守运行。 开发者社区已经形成了一套可靠的操作手册：容器化运行环境、使用 “Ralph Wiggum” 循环模式、安装四个关键 Hook 防止卡死、保持 CLAUDE.md 精简。有开发者记录了 27 小时连续自主会话完成 84 个任务；另一位在睡觉时让 Claude 构建了一个 15,000 行的游戏。但社区也反馈，大约 25% 的过夜产出会被丢弃，而且如果没有适当的防护措施，Claude 曾在至少一位开发者的机器上执行过 rm -rf /。以下是你今晚就能用上的完整设置方案。

一、消除人工干预的三种模式

Claude Code 提供三个级别的自主运行模式，每个级别都在安全性和速度之间做取舍。理解它们是所有过夜方案的基础。

模式 1：-p（print/pipe）标志 —— 所有自动化的核心。 这是非交互式运行模式。接收 prompt，执行到完成，输出到 stdout，然后退出。无需 TTY，512MB 内存的服务器也能跑。

1

claude -p "查找并修复 auth.py 中的 bug" --allowedTools "Read,Edit,Bash"

模式 2：--permission-mode auto —— 更安全的折中方案。 2026 年初推出，使用 Sonnet 4.6 分类器自动批准安全操作，同时阻止高风险操作。分类器分两阶段运作：快速判定（8.5% 误报率），对标记项目进行思维链推理（0.4% 误报率）。如果连续 3 次操作被拒绝或单次会话累计 20 次被拒，系统会升级到人工介入——或者在 headless 模式下直接终止。

1

claude --permission-mode auto -p "重构认证模块"

模式 3：--dangerously-skip-permissions —— 完全绕过权限。 所有操作无需确认直接执行。Anthropic 自己的安全研究员 Nicholas Carlini 也使用这个模式，但有一个关键前提：*”在容器里跑，不要在你的真实机器上。”* 一项调查发现 32% 的开发者使用这个标志时遭遇了意外的文件修改，9% 报告了数据丢失。

1
2

# 仅限 Docker/VM —— 绝对不要在宿主机上运行
claude --dangerously-skip-permissions -p "构建这个功能"

推荐的过夜运行方式是将 -p 与细粒度工具白名单 --allowedTools 结合使用，允许特定命令而非授予全面访问权限：

1
2
3
4

claude -p "修复所有 lint 错误并运行测试" \
 --allowedTools "Read" "Edit" "Bash(npm run lint:*)" "Bash(npm test)" "Bash(git *)" \
 --max-turns 50 \
 --max-budget-usd 10.00

--max-turns 和 --max-budget-usd 是无人值守会话的必备成本控制手段。没有它们，一个失控的循环可以在几分钟内烧光你的 API 预算。

二、Ralph Wiggum 循环：开发者的实际过夜方案

最经过实战验证的长时间自主工作模式是 Ralph Wiggum 循环——以《辛普森一家》中的角色命名，现已成为 Anthropic 官方插件。概念非常简单：一个 bash while 循环持续向 Claude 喂相同的 prompt。每次迭代中，Claude 查看当前文件状态和 git 历史，选择下一个未完成的任务，实现它，然后提交。

1
2
3
4
5

while true; do
 claude --dangerously-skip-permissions \
 -p "$(cat PROMPT.md)" 
 sleep 1
done

那位记录了 27 小时会话 的开发者使用了这个模式，配合一个详细的 prompt 文件，包含架构说明、目标、约束条件和明确的”完成”标准。他的核心发现：*”一句话 prompt 在一两个小时后就没劲了。27 小时的会话能持续下去，是因为 prompt 文件有足够多的上下文。”*

Prompt 文件比循环本身更重要。 一个有效的过夜 PROMPT.md 示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

# 任务：测试并加固认证系统

## 上下文
- 后端：Express + TypeScript，位于 src/api/
- 数据库：PostgreSQL，schema 在 prisma/schema.prisma
- 认证流程：JWT 中间件在 src/middleware/auth.ts

## 目标
- 查看 docs/plan.md，选择下一个未完成的任务
- 实现它，包含完善的错误处理
- 运行测试，修复失败，确认没有回归
- 做通用修复，不要打临时补丁
- 每完成一个任务后用描述性消息提交

## 成功标准
- 每次修改后所有测试通过
- 不会引入之前修复的回归
- 当 plan.md 中所有任务完成后输出 DONE

社区有几个工具扩展了这个基础循环。Ralph CLI 增加了速率限制（100次调用/小时）、熔断器、会话过期（默认24小时）和实时监控仪表板。Nonstop 增加了飞行前风险评估和阻塞决策框架——走之前输入 /nonstop 即可。Continuous-claude 自动化完整 PR 生命周期：创建分支、推送、创建 PR、等待 CI、合并。

三、防止过夜灾难的四个 Hook

开发者 yurukusa 记录了 108 小时无人值守运行，识别出七类过夜事故——包括 Claude 执行 rm -rf ./src/、进入无限错误循环、直接推送到 main 分支，以及产生每小时 8 美元的 API 费用。解决方案：四个关键 Hook，共同预防最常见的故障模式。

10 秒快速安装：

1

npx cc-safe-setup

Hook 1：No-Ask-Human 阻止 AskUserQuestion 工具调用，强制 Claude 自主做出决定，而不是坐在那里等几小时等人回复。这个 Hook 决定了 Claude 是整夜工作还是在晚上 11:15 卡住。在你坐在电脑前时，用 CC_ALLOW_QUESTIONS=1 覆盖。

Hook 2：Context Monitor 将工具调用次数作为上下文使用量的代理指标，在四个阈值（剩余 40%、25%、20%、15%）发出分级警告。在临界水平时，配套的空闲推送脚本会自动向终端注入 /compact 命令——两个进程，共 472 行代码，零人工干预。

Hook 3：Syntax Check 在任何文件编辑后立即运行 python -m py_compile、node --check 或 bash -n，在错误级联成 50 次调试之前就捕获它们。

Hook 4：Decision Warn 在执行前标记破坏性命令（rm -rf、git reset --hard、DROP TABLE、git push --force）。通过 CC_PROTECT_BRANCHES="main:master:production" 配置受保护分支。

在 .claude/settings.json 中配置：

1
2
3
4
5
6

{
 "permissions": {
 "allow": ["Bash(npm run lint:*)", "WebSearch", "Read"],
 "deny": ["Read(.env)", "Bash(rm -rf *)", "Bash(git push * main)"]
 }
}

四、tmux 设置与保持机器不休眠

Claude Code 的交互模式需要 TTY —— 不能用 nohup 或将其作为 systemd 服务运行（大约 15-20 秒后会因 stdin 错误崩溃）。tmux 是会话持久化的必备工具。

1
2
3
4
5
6
7
8
9
10
11
12
13

# 启动命名会话
tmux new -s claude-work

# 在其中启动 Claude
claude --permission-mode auto

# 分离（Claude 继续运行）：Ctrl+B，然后按 D

# 从任何地方重新连接（SSH、手机 Termius 等）
tmux attach -t claude-work

# 不连接就查看进度
tmux capture-pane -t claude-work -p -S -50

对于真正的 7×24 运行，社区推荐 VPS + Tailscale + tmux 方案：便宜的 VPS（Hetzner、Vultr、DigitalOcean）提供永不关机的算力，Tailscale 提供私有网络，mosh 在不稳定网络上保持连接持久性。给 Claude 一个任务，分离，合上笔记本，明天再回来。

macOS 防止休眠：

1
2
3
4
5

# 绑定到 Claude 进程
caffeinate -i -w $(pgrep -f claude) &

# 或者在接通电源时全局禁用休眠
sudo pmset -c sleep 0

管理多个并行会话方面，Amux 是一个约 12,000 行的 Python 文件，提供 Web 仪表板、手机 PWA 监控、自愈看门狗（自动重启崩溃会话）、按会话 token 追踪和 git 冲突检测。Codeman 提供类似的 Web UI，带 xterm.js 终端，支持最多 20 个并行会话。

一个强大的过夜 agent tmux 配置：

1
2
3
4
5
6
7
8
9

#!/bin/bash
tmux new-session -d -s claude-dev
tmux rename-window -t claude-dev:0 'Claude'
tmux new-window -t claude-dev:1 -n 'Tests'
tmux new-window -t claude-dev:2 -n 'Logs'
tmux send-keys -t claude-dev:0 'claude --permission-mode auto' Enter
tmux send-keys -t claude-dev:1 'npm run test:watch' Enter
tmux send-keys -t claude-dev:2 'tail -f logs/app.log' Enter
tmux attach-session -t claude-dev

五、CLAUDE.md 与长时间运行的上下文管理

过夜失败的最大原因是上下文窗口耗尽。Claude Code 的上下文窗口大约 200K token，使用率超过 70% 时性能开始下降。自动压缩在接近阈值时触发，但会丢失信息——仅保留 20-30% 的细节。有开发者报告 Claude 压缩后遗忘了所有内容，重新开始同一个任务，浪费了三个小时。

解决方案是检查点/交接模式，能够在上下文重置后存活：

1
2
3
4
5
6

# 在 CLAUDE.md 中
当上下文变大时，将当前状态写入 tasks/mission.md。
包括：已完成的、下一步的、被阻塞的、未解决的问题。
错误处理：最多重试 3 次。如果没有进展，记录到
pending_for_human.md 然后转到下一个任务。
压缩前，务必保存完整的已修改文件列表。

将 CLAUDE.md 控制在 200 行以内——每个词在每个会话中都消耗 token。从 800 行切换到 100 行的开发者达成社区共识：更短的配置实际上表现更好，因为 Claude 不会忽略被噪音淹没的指令。使用”仅在不可逆时才提问”规则，将提问频率降低约 80%：

1
2
3
4
5
6

# 自主运行的决策规则
- 技术方案不确定 → 选择传统方案
- 两种可行实现 → 选择更简单的那个
- 尝试 3 次后仍有错误 → 记录到 blocked.md，切换任务
- 需求模糊 → 应用最合理的理解，记录假设
- 永远不要提问。做出最佳判断然后继续。

CLAUDE.md 文件是分层的：~/.claude/CLAUDE.md（全局）、./CLAUDE.md（项目级，git 追踪）、.claude/CLAUDE.local.md（个人覆盖，gitignore）。自主运行时，全局文件保持最小，把运行特定指令放在项目文件中。

关键 token 节省技巧：在里程碑后主动使用 /compact，而非等待自动压缩；对独立任务使用子 agent（每个有自己的上下文窗口）；不相关的工作启动新会话；积极使用 .claudeignore 排除无关文件。

六、过夜运行的速率限制处理

速率限制作为三个独立的、重叠的约束运作：每分钟请求数、每分钟输入 token 数、每分钟输出 token 数。一个可见的命令在内部可能产生 8-12 个 API 调用（lint、修复、测试、修复循环）。15 次迭代后，单个请求可能发送 20 万+ 输入 token。

过夜运行速率限制生存策略：

在非高峰时段运行。 Anthropic 确认工作日太平洋时间早 5 点到 11 点限制更严格。过夜运行和周末会话完全避开高峰期限流——恰好就是你在睡觉的时候。

利用 Ralph 循环的内置重试。 运行 while 循环时，速率限制错误只会导致当前迭代失败，但循环不在乎——它在速率限制窗口重置后的下一次迭代中重试。有开发者警告：*”不要在 API/按用量计费模式下运行——重试会烧光你的预算。”*

运行中切换模型。 Sonnet 能处理 60-70% 的常规任务，每 token 成本比 Opus 低约 1.7 倍。过夜工作设置 --model sonnet，将 Opus 留给复杂推理。也可以设置 --fallback-model sonnet，让 Claude 在主模型过载时自动降级。

Token 消耗的真实数据：20 条消息会话消耗约 105,000 token；30 条消息会话跳到 232,000 token。大约 98.5% 的 token 花在重新读取对话历史——只有 1.5% 用于实际输出。这就是为什么全新会话和积极压缩如此重要。

成本估算：持续运行 Sonnet 大约 $10.42/小时。基于 cron 每 15 分钟运行一次的 agent，预计约 $48/天。使用 --max-budget-usd 作为硬上限。

七、CI/CD 流水线与 Cron 任务集成

对于计划性的自动化工作，Claude Code 可直接与 CI/CD 系统集成。官方 GitHub Action 是 anthropics/claude-code-action@v1：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

name: Claude Code Review
on:
 pull_request:
 types: [opened, synchronize]
jobs:
 review:
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v4
 with:
 fetch-depth: 0
 - uses: anthropics/claude-code-action@v1
 with:
 anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
 prompt: "审查这个 PR 的安全和代码质量问题。"
 claude_args: "--max-turns 5 --model claude-sonnet-4-6"

对于基于 cron 的自主 agent，Boucle 模式通过 state.md 文件在运行之间维持状态：

1
2
3
4
5
6
7
8
9
10
11
12

#!/bin/bash
# run-agent.sh —— 由 cron 调用
STATE="$HOME/agent/state.md"
LOG="$HOME/agent/logs/$(date +%Y-%m-%d_%H-%M-%S).log"

claude -p "你是一个自主 agent。读取你的状态，决定做什么，
然后用你学到的内容更新 state.md。
$(cat $STATE)" \
 --allowedTools Read,Write,Edit,Bash \
 --max-turns 20 \
 --max-budget-usd 1.00 \
 --bare 2>&1 | tee "$LOG"

1
2

# crontab -e
0 * * * * /path/to/run-agent.sh

200 次迭代后的关键教训：state.md 必须保持在 4KB 以下（它会被注入每个 prompt），使用结构化键值对而非散文，并添加文件锁防止重叠运行。每次迭代后 git commit——git log 就是你最好的调试工具。

CI 环境使用 --bare 模式（跳过 hook、MCP 服务器、OAuth 和 CLAUDE.md 加载，最快最可复现的执行方式）和 --permission-mode dontAsk（拒绝所有未显式允许的操作——自动化环境中最安全的模式）。

八、已知陷阱与可能出错的地方

社区已广泛记录了以下故障模式：

最重要的单一安全措施是容器化。多位经验丰富的开发者独立推荐使用带网络隔离的 Docker：

1
2
3
4
5

docker run -it --rm \
 -v $(pwd):/workspace -w /workspace \
 --network none \
 -e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
 claude-code:latest --dangerously-skip-permissions -p "$(cat PROMPT.md)"

正如一位开发者所说：*”用 --dangerously-skip-permissions 运行 Claude Code 就像不做防护措施。所以用个套… 我是说容器。”*

九、今晚的快速启动清单

15 分钟设置过夜自主运行：

1. 创建 git 检查点：git add -A && git commit -m "pre-autonomous checkpoint"
2. 安装四个关键 Hook：npx cc-safe-setup
3. 编写 PROMPT.md，包含架构上下文、任务列表、成功标准，以及每完成一个任务就提交的指令
4. 启动 tmux 会话：tmux new -s overnight
5. 防止休眠（macOS）：caffeinate -s &
6. 启动循环：

1
2
3
4
5
6
7
8

while true; do
 claude -p "$(cat PROMPT.md)" \
 --allowedTools "Read" "Edit" "Bash(npm run *)" "Bash(git *)" \
 --max-turns 30 \
 --max-budget-usd 5.00 \
 --permission-mode acceptEdits
 sleep 2
done

7. 分离 tmux：Ctrl+B，然后按 D
8. 去睡觉

早上起来：tmux attach -t overnight，然后查看 git log（git log --oneline）看 Claude 完成了什么。预计保留大约 75% 的产出，丢弃 25%。这很正常——正如一位开发者说的，*”不是完美，甚至不是最终版，但是在前进。”*

十、总结

先用 plan 模式，把 PRD.md 和 TODO.md 生成好。

• 安装 cc-safe-setup

  1	npx cc-safe-setup

• 安装 format-claude-stream

  1	npm install -g @khanacademy/format-claude-stream

• 编写项目的 CLAUDE.md

  1 2 3

  - 当上下文变大时，将当前状态写入 tasks/mission.md。包括：已完成的、下一步的、被阻塞的、未解决的问题。 - 错误处理：最多重试 3 次。如果没有进展，记录到 pending_for_human.md 然后转到下一个任务。 - 压缩前，务必保存完整的已修改文件列表。

• 编写 PROMPT.md

  1 2 3 4 5 6 7 8 9 10 11 12 13 14

  ## 目标 - 查看 TODO.md，选择一个未完成的任务执行 - 执行的代码必须包含测试用例并测试通过 - 每做完一个任务，及时提交 Git，并在 TODO.md 标记为已完成 - 当所有任务都完成后，在 TODO.md 中顶部注明：“全部任务已完成” ## 要求 - 技术方案不确定 → 选择传统方案 - 两种可行实现 → 选择更简单的那个 - 需求模糊 → 应用最合理的理解，记录假设 - 永远不要提问，做出最佳判断然后继续 ## 环境（如有） # - CLOUDFLARE API 在 key.md 中

• 编写 key.md

  1 2	CLOUDFLARE_API_TOKEN=xxx CLOUDFLARE_ACCOUNT_ID=xxx

• 编写 nostop.sh

  1 2 3 4 5 6 7 8 9

  mkdir -p logs while true; do claude -p "$(cat PROMPT.md)" \ --dangerously-skip-permissions --model opus \ --output-format stream-json --verbose \ tee "logs/$(date +%Y%m%d_%H%M%S).jsonl" \ | format-claude-stream sleep 60 done

2026-04-12 22:44:49

背景

Claude Code 支持多种认证方式，包括 AWS Bedrock、Google Vertex AI、Anthropic API Key 和 Claude 订阅（Pro/Max/Team/Enterprise）。当你从 Bedrock 切换到 Team 订阅时，需要清除 Bedrock 的配置，否则 Claude Code 会一直走 Bedrock 通道。

核心问题

使用 Bedrock 认证时，/login 和 /logout 命令是被禁用的（官方设计如此）。因此你无法在 Bedrock 模式下直接切换登录方式。

Bedrock 配置的来源有两种：

1. 环境变量 — 通过 export 或写在 ~/.zshrc / ~/.bashrc 中
2. settings.json — 写在 ~/.claude/settings.json 的 env 字段中

很多用户（尤其是通过 setup wizard 配置的）的 Bedrock 设置是写在 settings.json 里的，单纯 unset 环境变量并不能解决问题。

切换步骤

第一步：检查 Bedrock 配置来源

1
2
3
4
5

# 检查环境变量
env | grep -i -E "claude_code_use|anthropic|bedrock|aws"

# 检查 settings.json
cat ~/.claude/settings.json

如果在 settings.json 中看到类似以下内容，说明 Bedrock 配置在这里：

1
2
3
4
5
6
7
8

{
  "env": {
    "CLAUDE_CODE_USE_BEDROCK": "1",
    "AWS_REGION": "us-west-2",
    "ANTHROPIC_MODEL": "arn:aws:bedrock:...",
    "CLAUDE_CODE_AWS_PROFILE": "default"
  }
}

第二步：清除 Bedrock 配置

如果配置在 settings.json 中，编辑 ~/.claude/settings.json，删除 env 中所有 Bedrock 相关的键值对：

• CLAUDE_CODE_USE_BEDROCK
• AWS_REGION
• ANTHROPIC_MODEL
• CLAUDE_CODE_AWS_PROFILE
• CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS（Bedrock 专用）
• CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC（Bedrock 专用）

保留你仍需要的配置（如代理、权限设置等）。清理后的文件示例：

1
2
3
4
5
6
7
8
9
10
11
12

{
  "env": {
    "HTTP_PROXY": "http://your-proxy:8118",
    "HTTPS_PROXY": "http://your-proxy:8118"
  },
  "permissions": {
    "allow": [
      "Bash(*)"
    ],
    "defaultMode": "dontAsk"
  }
}

如果配置在环境变量中，清除相关变量：

1
2
3
4
5

unset CLAUDE_CODE_USE_BEDROCK
unset ANTHROPIC_MODEL
unset ANTHROPIC_API_KEY
unset AWS_REGION
unset CLAUDE_CODE_AWS_PROFILE

同时检查并清理 shell 配置文件：

1
2

grep -r "CLAUDE_CODE_USE_BEDROCK\|ANTHROPIC_MODEL\|ANTHROPIC_API_KEY" \
  ~/.zshrc ~/.bashrc ~/.zprofile ~/.bash_profile 2>/dev/null

第三步：重新启动 Claude Code

1

claude

此时应该会弹出登录方式选择界面，选择 「Claude account with subscription」，然后在浏览器中授权你的 Team 计划。

第四步：确认切换成功

启动后，欢迎界面底部应显示类似：

1

Sonnet 4.6 · Claude Pro（或 Team）

而不是之前的 arn:aws:bedrock:...。

也可以在交互界面中输入 /status 确认当前认证方式。

第五步：切换模型（可选）

如果需要使用 Opus 模型，在交互界面中输入：

1

/model

用方向键选择 Opus 即可。

认证优先级

Claude Code 的认证优先级从高到低为：

1. 云提供商凭据（CLAUDE_CODE_USE_BEDROCK / CLAUDE_CODE_USE_VERTEX / CLAUDE_CODE_USE_FOUNDRY）
2. ANTHROPIC_AUTH_TOKEN 环境变量
3. ANTHROPIC_API_KEY 环境变量
4. apiKeyHelper 脚本
5. 订阅 OAuth 凭据（/login）

只要高优先级的认证方式存在，低优先级的就不会生效。所以必须彻底清除 Bedrock 配置，订阅认证才能生效。

注意事项

• 代理地址：Bedrock 用的代理可能无法访问 api.anthropic.com，切换后可能需要更换代理或去掉代理配置。
• Premium 席位：Team 计划需要 Premium 席位才能使用 Claude Code，确认管理员已分配。
• 用量共享：Team 计划的用量限额在 Claude 网页端和 Claude Code 之间是共享的。
• Memory 延续：CLAUDE.md 等本地文件不受认证方式影响，切换后照常保留。对话历史不会跨会话保存，这点两种方式一样。

2026-04-11 23:07:00

你有没有这种体验：让 AI 帮你写个页面，它生成的代码颜色全是瞎编的、间距全靠猜、按钮样式跟你们产品完全不搭？

然后你甩给它一份设计规范的 PDF，指望它能“学会”你们的设计体系。

结果呢？AI 看 PDF 基本等于盲人摸象——它看到的是一堆碎片化的文字和完全无法理解的截图。那些精心排版的视觉示例，在 AI 眼里跟噪音差不多。

问题不是 AI 不行，而是我们给 AI 的“学习资料”不对。

传统设计规范的问题

传统设计规范长这样：一份精美的 PDF，里面有品牌色卡、组件截图、do/don’t 的对比图、各种排版示例。

这东西给人看，完美。给 AI 看，灾难。

原因很简单：

第一，PDF 是视觉媒介，AI 是文本动物。 PDF 里那些色卡截图，AI 根本“看”不出来里面的色值是什么。它需要的是 #1A73E8 这个字符串，不是一个蓝色方块的图片。

第二，设计规范的“规则”通常是散文式的。 比如“不要在一个页面里放太多主按钮”——这句话人类一看就懂，但 AI 很难把它转化成一个可执行的判断。太多是多少？什么算主按钮？什么算一个页面？

第三，知识是碎片化的。 颜色写在第 3 页，间距写在第 7 页，按钮的规范在第 12 页，而按钮用到的颜色和间距需要 AI 自己去关联。这种跨页面的信息拼装，AI 做起来很吃力。

核心思路：把设计决策变成结构化数据

一句话总结：视觉示例给人看，结构化数据给 AI 读。

具体来说，就是把传统设计规范里的每一个设计决策，都翻译成 AI 能精确解析的格式。

那用什么格式呢？我让 Claude Opus 帮我调研了一下，它推荐的方案是：Markdown + JSON + YAML 的组合。其中：

• Markdown 负责描述性的内容：设计原则、使用场景、什么时候该用什么不该用
• JSON 负责精确的数值定义：颜色值、字号、间距、阴影
• YAML 负责组件级的结构化规范：组件的变体、状态、约束规则

为什么不统一用一种格式？因为各有所长。JSON 适合定义纯数据（Design Token），YAML 适合描述有层次的组件规范（因为可读性更好），Markdown 适合写需要段落和叙事的内容（设计原则、模式指引）。

具体分五步来做

1. Design Token 化：把所有“魔法数字”抽出来

传统规范里，设计师说“主色调是品牌蓝”，然后在 PDF 里放一个色块。

AI 友好的方式是把它变成一个 Token：

1
2
3
4
5
6
7
8
9
10
11
12

{
  "color": {
    "brand": {
      "primary": {
        "value": "#1A73E8",
        "usage": "主操作按钮、重要链接、选中态",
        "contrast_on_white": "4.6:1",
        "wcag_aa": true
      }
    }
  }
}

注意这里不只有色值，还有 usage（什么场景用）和 wcag_aa（是否满足无障碍标准）。这些上下文信息对 AI 来说极其重要——它不只要知道“是什么颜色”，还要知道“什么时候用”和“为什么选这个颜色”。

同理，字号、间距、圆角、阴影、动画时长……所有数值类的设计决策，都应该 Token 化。

2. 组件规范用结构化 Schema 描述

传统规范里，一个按钮组件的描述可能是一页截图加几段说明文字。

AI 友好的方式是用 YAML 写一个完整的结构化定义：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

component: Button

variants:
  - name: primary
    description: "主操作按钮，页面中最重要的行动号召"
    styles:
      background: "{color.brand.primary}"
      text_color: "#FFFFFF"
      border_radius: "{border_radius.md}"

sizes:
  - name: md
    height: "40px"
    padding: "0 {spacing.md}"
    font_size: "{typography.scale.body-md.size}"

states: [default, hover, active, focus, disabled, loading]

这里面有几个关键设计：

用花括号引用 Token，比如 {color.brand.primary}。这样 AI 在生成代码时，会自动去 Token 文件里查对应的值，而不是硬编码一个色值。整个系统是关联的。

明确列出所有状态。人类设计师可能觉得“hover 状态不用说大家都知道”，但 AI 需要你把它列出来。缺什么它就不做什么。

有变体（variants）和尺寸（sizes）的穷举。 AI 最擅长在有限集合里做选择，而不是在模糊描述里做推断。

3. 把 do/don’t 改写成可执行的规则

这是最关键的一步。

传统规范里的“Don’t”通常配一张错误示例截图，AI 完全看不懂。

AI 友好的方式是把它写成带 ID、有严重等级、能机器检查的规则：

1
2
3
4
5
6
7
8
9
10
11
12

rules:
  - id: btn-001
    rule: "同一视图中最多一个 primary 按钮"
    severity: error
    rationale: "多个 primary 按钮导致用户无法识别主操作"

  - id: btn-003
    rule: "按钮文案不超过 6 个中文字符"
    severity: warning
    examples:
      correct: ["提交订单", "确认删除", "开始学习"]
      incorrect: ["好的", "订单信息", "下一步操作确认提交"]

这种格式有几个好处：

• 有唯一 ID：AI 审查代码时可以引用“违反了规则 btn-001”
• 有严重等级：error 是必须修的，warning 是建议修的，AI 可以区分优先级
• 有原因：rationale 告诉 AI“为什么”，当遇到边缘情况需要取舍时，AI 能做更合理的判断
• 有正反例：而且是文字形式的，不是截图

4. 提供“AI 入口文件”

你的设计规范可能有几十个文件，AI 不知道该先看哪个。你需要一个 README.md 作为入口，就像给 AI 画一张地图：

1
2
3
4
5
6
7
8
9
10
11
12

## AI 使用指引

### 生成 UI 代码时
1. 先读取 tokens/ 中的变量，禁止硬编码颜色/字号/间距值
2. 查找对应 components/*.yaml 获取组件结构和约束规则
3. 查阅 patterns/*.md 确认页面级布局要求
4. 检查 accessibility.md 确保符合无障碍标准

### 审查 UI 代码时
1. 逐条检查组件 YAML 中的 rules 字段
2. 验证 Token 引用是否正确
3. 检查 severity: error 的规则是否被违反

这个入口文件告诉 AI 三件事：有哪些文件、每个文件是干嘛的、不同任务应该按什么顺序查阅哪些文件。

5. 设计原则要可操作化

传统规范里的设计原则通常很抽象：“我们追求简洁”。

AI 友好的方式是让原则可操作——不只说“是什么”，还说“怎么用”和“冲突时怎么办”：

1
2
3
4

### 清晰优先于美观
- **含义**: 用户能否在 3 秒内理解界面意图，比视觉精致更重要
- **实践**: 信息层次分明，操作路径可预期，文案直白无歧义
- **权衡**: 当装饰性元素影响信息传达时，移除装饰性元素

特别是要提供一个 原则冲突解决矩阵。比如“清晰”和“包容性”冲突时谁优先？“性能”和“一致性”冲突时呢？人类设计师靠直觉判断，AI 需要明确的规则。

推荐的文件结构

说了这么多，最终的目录结构长这样：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

design-system/
├── README.md              ← AI 入口，索引整个规范
├── principles.md          ← 设计原则 + 冲突解决矩阵
├── accessibility.md       ← 无障碍要求 + AI 审查清单
├── tokens/
│   ├── colors.json        ← 品牌色、功能色、中性色
│   ├── typography.json    ← 字体、字号阶梯、行高
│   ├── spacing.json       ← 间距、栅格、断点
│   ├── elevation.json     ← 阴影、层级
│   └── motion.json        ← 动画时长、缓动函数
├── components/
│   ├── button.yaml        ← 按钮规范
│   ├── input.yaml         ← 输入框规范
│   ├── modal.yaml         ← 弹窗规范
│   └── card.yaml          ← 卡片规范
└── patterns/
    ├── form-layout.md     ← 表单布局模式
    ├── error-handling.md  ← 错误处理策略
    ├── responsive.md      ← 响应式断点规则
    └── dark-mode.md       ← 深色模式适配

每层的分工很清晰：

• tokens/ 是最底层的原子变量，纯数据，JSON 格式
• components/ 是组件级规范，结构化描述，YAML 格式
• patterns/ 是页面级模式，需要叙事和流程说明，Markdown 格式

一些实操建议

不要一步到位。 你不需要一次把整个设计规范都改造完。可以先从 Design Token 开始——把颜色和字号从 PDF 里抽出来做成 JSON 文件，这一步投入产出比最高。

保持两个版本同源。 理想情况下，JSON/YAML 是“源文件”，PDF 版本从源文件自动生成。这样改一处，两边都更新。如果做不到自动生成，至少保证人工同步。

给每个决策加上“为什么”。 这是很多人最容易忽略的。AI 在遇到边缘情况时，rationale 字段就是它做判断的依据。没有 rationale，它只会机械执行规则；有了 rationale，它能理解意图，做出更灵活的判断。

把规范放到代码仓库里。 设计规范不应该是一个飞书文档或者 Figma 链接，而是一个 Git 仓库里的文件夹。这样 AI 工具可以直接读取，开发者可以在 CI/CD 里做自动检查，版本变更有迹可循。

实际测试。 改造完之后，拿你的 AI 工具（Claude、Cursor、Copilot 等）实际跑一遍：让它基于你的设计规范生成一个页面，看看它是不是真的引用了 Token、遵守了规则。不好使就迭代。

最后

AI 时代的设计规范，本质上是一个 API——它不再只是给人“阅读”的文档，而是给机器“调用”的接口。

格式变了，但设计的本质没变。你仍然需要好的设计判断来决定什么颜色、什么间距、什么交互模式。只是表达方式要变一变：从“让人看懂”升级为“人机双读”。

如果你的设计师不知道如何输出上面的文件，没关系，把这篇文章发给你的 AI Agent（推荐使用 Claude Opus 4.6），然后说：我需要按照文章中的方案来产生一套面向 AI 的设计规范，你来帮我完成，现在你告诉我需要哪些文件和资料，我来负责提供。

放心，AI 会一步一步带着你完成这份规范。

希望对你有用。

2026-04-09 06:56:00

OpenClaw Memory Wiki 技术文档

基于 OpenClaw v2026.4.7 最新版本整理，更新日期：2026-04-08

目录

• 概述
• 核心架构
• Memory Wiki 插件
• Vault 模式
• 页面组织结构
• 结构化 Claim/Evidence 模型
• 关键能力
• 矛盾检测与聚类
• 新鲜度加权搜索
• 编译摘要（Compiled Digests）
• 过时性仪表盘
• Wiki 工具集
• CLI 命令参考
• Obsidian 集成
• Dreaming 系统（实验性）
• 搜索后端与混合检索
• 配置参考
• v2026.4.7 更新要点
• 参考资料

概述

OpenClaw 是一个开源的个人 AI 代理框架，其记忆系统采用 基于文件的记忆模型——所有持久化信息以 Markdown 文件形式存储在代理工作空间中（默认路径：~/.openclaw/workspace）。系统不维护任何隐藏状态，只有显式写入磁盘的内容才计入记忆。

Memory Wiki 是 OpenClaw 记忆体系中的高级层，作为可选的伴生插件（memory-wiki），将持久化记忆编译为一个具有溯源能力的知识库（vault），支持确定性页面布局、结构化声明（claims）、矛盾追踪和机器可读摘要。

核心架构

OpenClaw 的记忆系统由三层文件构成：

核心记忆工具：

• **memory_search**：语义搜索，匹配概念含义而非精确措辞
• **memory_get**：检索特定的记忆文件或指定行范围

Memory Wiki 作为补充层叠加在核心记忆之上，不替换核心记忆插件。

Memory Wiki 插件

Vault 模式

Memory Wiki 支持两种运行模式：

1. Isolated（隔离）模式

1
2
3
4
5

memory-wiki:
 vaultMode: "isolated"
 vault:
 path: "~/.openclaw/wiki/main"
 renderMode: "obsidian"

• Wiki 拥有独立的 vault 和数据源
• 不依赖 memory-core
• 适用于：希望 wiki 作为独立的、经过策展的知识库

2. Bridge（桥接）模式

1
2

memory-wiki:
 vaultMode: "bridge"

• 通过公共插件 SDK 接口读取活跃记忆插件的公开记忆 artifacts 和事件
• 不直接访问私有插件内部实现
• 适用于：希望 wiki 编译和组织核心记忆插件导出的 artifacts

建议：除非明确需要桥接模式，否则优先选择 isolated 模式。

页面组织结构

Wiki vault 采用确定性目录布局：

1
2
3
4
5
6
7
8
9
10
11

~/.openclaw/wiki/main/
├── sources/ # 导入的原始材料、桥接页面
├── entities/ # 持久对象：人物、系统、项目
├── concepts/ # 观念、抽象、模式、策略
├── syntheses/ # 编译摘要、维护性汇总
├── reports/ # 生成的报告
├── _attachments/ # 附件资源
├── _views/ # 视图定义
└── .openclaw-wiki/ # 托管内容与缓存
 └── cache/
 └── claims.jsonl # 编译后的声明摘要

关键目录说明：

结构化 Claim/Evidence 模型

Memory Wiki 的核心创新是将知识从自由文本升级为 结构化声明。每个页面可在 frontmatter 中携带结构化的 claims：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

---
id: entity.kubernetes
claims:
 - claim: "Kubernetes 默认调度器使用 bin-packing 策略"
 confidence: 0.85
 source: "sources/k8s-scheduler-doc"
 updated: 2026-03-15
 status: active
 - claim: "Helm v4 已移除 Tiller 依赖"
 confidence: 0.95
 source: "sources/helm-release-notes"
 updated: 2026-04-01
 status: active
---

# Kubernetes

正文内容...

Claim 字段说明：

Claims 可被追踪、评分、质疑和溯源，使 wiki 的行为更像一个 信念层（belief layer） 而非被动的笔记堆。

关键能力

矛盾检测与聚类

wiki_lint 工具能自动扫描 vault 中的结构性问题：

• 矛盾检测：发现语义上互相冲突的 claims
• 矛盾聚类（Contradiction Clustering）：将相关的矛盾声明分组，便于集中解决
• 溯源缺口：标记缺少 source 引用的 claims
• 开放问题：识别尚未解决的疑问

新鲜度加权搜索

wiki_search 的搜索排序综合考虑：

• 语义相关性：基于向量相似度的概念匹配
• 关键词匹配：精确标识符和代码符号的 BM25 匹配
• 新鲜度权重（Freshness Weighting）：最近更新的 claims 获得更高排名
• 置信度得分：高置信度的声明优先展示

编译摘要（Compiled Digests）

为避免代理和运行时代码在查询时解析 Markdown 页面，Memory Wiki 维护编译后的摘要：

1

.openclaw-wiki/cache/claims.jsonl

每行为一个 JSON 对象，包含 claim 的完整元数据。代理可直接读取此文件进行高效查询，无需遍历页面。

过时性仪表盘

Memory Wiki 内置 Staleness Dashboard，可视化展示：

• 各 claim 的最后更新时间
• 过时（stale）声明的数量与分布
• 需要审查的知识区域

Wiki 工具集

Memory Wiki 插件注册以下工具供代理使用：

使用建议：

• 当溯源（provenance）重要时，使用 wiki_search / wiki_get 而非通用 memory_search
• 对元数据更新使用 wiki_apply，避免自由编辑页面
• 有意义的变更后运行 wiki_lint

CLI 命令参考

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

# 状态与诊断
openclaw wiki status # 查看 vault 状态
openclaw wiki doctor # 诊断 vault 健康问题

# 初始化与数据导入
openclaw wiki init # 初始化新 vault
openclaw wiki ingest ./notes/alpha.md # 导入外部文档

# 编译与质量检查
openclaw wiki compile # 重新编译 claims 摘要
openclaw wiki lint # 结构检查与矛盾检测

# 搜索与检索
openclaw wiki search "kubernetes" # 搜索 wiki 内容
openclaw wiki get entity.alpha # 获取指定页面

# 综合与应用
openclaw wiki apply synthesis # 应用综合更新

# Obsidian 集成
openclaw wiki obsidian status # 检查 Obsidian 集成状态

Obsidian 集成

Memory Wiki 支持与 Obsidian 笔记软件深度集成：

1
2
3
4
5
6

memory-wiki:
 obsidian:
 enabled: true
 useOfficialCli: true # 使用 Obsidian 官方 CLI (v1.12+)
 vaultName: "openclaw-wiki"
 openAfterWrite: false

官方 Obsidian CLI（v1.12+）提供完整的 vault 自动化能力，包括：文件管理、每日笔记、搜索、任务、标签、属性、链接、书签、模板、主题、插件、同步与发布。

当 renderMode 设为 "obsidian" 时，Wiki 页面输出为 Obsidian 兼容格式，可直接在 Obsidian 中浏览和编辑。

Dreaming 系统（实验性）

Dreaming 是一个可选的后台巩固流程，与 Memory Wiki 配合工作：

1. 收集（Collect）：从每日笔记中提取短期信号
2. 评分（Score）：基于阈值（得分、召回频率、查询多样性）筛选候选项
3. 晋升（Promote）：将合格项目提升至长期记忆（MEMORY.md）
4. 记录（Document）：在 DREAMS.md 中写入阶段性摘要

v2026.4.7 中 Dreaming 系统的改进：

• 支持将脱敏的会话转录导入 dreaming 语料库
• 按天生成 session-corpus 笔记
• 游标检查点与晋升/诊断支持
• 在每日笔记导入前剥离托管的 Light Sleep 和 REM 块

搜索后端与混合检索

Memory Wiki 的搜索依托 OpenClaw 的混合检索架构：

当配置了 embedding provider 时（支持 OpenAI、Gemini、Voyage、Mistral），wiki_search 采用 混合搜索 策略：

• 向量相似度：语义理解层面的概念匹配
• BM25 关键词匹配：精确标识符与代码符号匹配
• 新鲜度加权：近期更新的内容获得排名提升

v2026.4.7 新增了当 sqlite-vec 不可用或向量写入降级时的显式警告。

配置参考

完整的 Memory Wiki 插件配置示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

plugins:
 memory-wiki:
 enabled: true
 vaultMode: "isolated" # "isolated" | "bridge"
 vault:
 path: "~/.openclaw/wiki/main"
 renderMode: "obsidian" # "obsidian" | "plain"
 obsidian:
 enabled: true
 useOfficialCli: true
 vaultName: "openclaw-wiki"
 openAfterWrite: false
 ingest:
 autoIndex: true
 search:
 backend: "builtin" # "builtin" | "qmd" | "honcho"
 freshnessWeight: 0.3 # 新鲜度权重系数
 lint:
 contradictionClustering: true
 stalenessThresholdDays: 30
 dashboard:
 enabled: true

v2026.4.7 更新要点

OpenClaw v2026.4.7 是 Memory Wiki 的重要里程碑版本，恢复了完整的 memory-wiki 栈：

Memory Wiki 核心恢复

• 插件 + CLI + sync/query/apply 工具链
• Memory-host 集成
• 结构化 claim/evidence 字段
• 编译摘要检索
• Claim 健康度 linting
• 矛盾聚类
• 过时性仪表盘
• 新鲜度加权搜索

其他相关更新

• 推理中心：新增 openclaw infer hub，支持跨 model/media/web/embedding 的 provider 推理工作流
• 媒体生成：工具/媒体生成支持跨 provider 自动降级，保留意图
• Webhook 集成：内置 webhook ingress 插件，支持外部自动化创建和驱动 TaskFlow
• 向量召回警告：sqlite-vec 不可用时显式提醒
• Dreams 配置感知：Dreams 配置读写现在尊重选定的 memory slot 插件

参考资料

• OpenClaw GitHub Releases
• OpenClaw v2026.4.7 Release Notes
• OpenClaw Memory 概念文档
• OpenClaw CHANGELOG
• Memory & Search - DeepWiki
• OpenClaw Memory Wiki 官方文档
• Luke The Dev 关于 v2026.4.7 的推文

2026-04-06 14:22:59

背景和问题

我有一个老的域名：devtang.com，上面利用 GitHub Pages 搭了我的 博客。这个域名注册很多年了，一直在 Godaddy 上续费，并且用 DNSPod (后来被阿里收购) 做解析。

我一直想迁移到 Cloudflare，但是域名转移的操作很繁琐，所以一直没有下决心推进。

这次，我想试试用 Claude Cowork 功能帮我做这个事儿。整个流程下来，感觉还挺顺畅的，所以给大家分享一下。

我觉得 AI 时代这些工作的工作流都有变化，所以说分享这样的工作流，有助于大家建立这种基于 AI Agent 的工作模式迁移。

操作流程

在使用前需要先安装好 Claude in Chrome 插件，然后执行如下操作：

1、我首先打开 Godaddy 和 Cloudflare 官网，登录上去。然后打开 Claude in Chrome 的浏览器面板。输入如下提示词：

1

我要将域名 devtang.com 从 godaddy 转移到 cloudflare，帮我继续转移。

Claude 给出了如下的操作步骤，点击 Approve Plan。

2、Claude 开始在 Godaddy 和 Cloudflare 上操作，有两次它停下来了，需要我给它发邮箱里面的授权码。于是我打开邮箱把授权码发给它。

3、操作继续，在操作过程中，我可以随意切换 Tab 看它的操作过程，也可以看它的 thinking 的过程。它其实每一步都是通过截图确认操作，也会中间停留 3-5 秒（可能是为了防止被误别成机器人）。

因为它也会停留，所以我有时候会帮它直接点击了，让操作更快一点。这也丝毫不会影响后续的工作，因为它每一步都会截图确认。

最后我看到了操作确认信息，告诉我转移成功。

迁移 GitHub Pages 到 Cloudflare Pages

Cloudflare Pages 支持无限流量，并且全球有多处结点，速度比 GitHub Pages 快。我把域名迁移过去之后，又进一步使用 Cloudflare 的 Pages 功能，将博客重新部署到了 Cloudflare 上。

具体步骤如下：

• 在 https://dash.cloudflare.com/，选择 “Build”->”Compute”->”Workers & Pages”，进入 Workers & Pages 页面。
• 选择页面上的 “Create Application” 按钮
• 在新的页面，点击最底部的小字：Looking to deploy Pages? Get started。这个字特别不起眼，如下图：

• 在页面上配置相关信息，我配置的内容如下：
  • 选择 “Import an existing Git repository”，选择你在 GitHub 上的博客仓库。
  • Production branch: source 分支。
  • Framework preset: None
  • Build command：npx hexo generate
  • Build output directory: public
  • 环境变量：
    • NODE_VERSION 设置为 24
    • NPM_VERSION 设置为 11

以上设置好就可以测试了，测试遇到问题的话，把 error log 复制发给 claude，claude 会告诉你怎么改。

配置完之后，它默认的域名是 https://tangqiaoboy.pages.dev, 你可以用刚刚迁移好的域名给它设置一个新的域名，像我就设置成了 https://www.devtang.com/。如下图：

利用这个 Pages 可以干很多事情，比如我看到一个人就拿它发布了一个 巴菲特致股东的信 网站。不需要买服务器，也不需要买域名，也不用担心流量不够。

小结

• 借助 Claude Cowork, 我们可以把复杂的工作流程全部交给 AI。
• 在 Claude in Chrome 工作的时候，我们也可以随时接管网页操作，帮他把中间的步骤给衔接上。
• 操作过程中如果一直没有推进，可以查看 claude thinking 的过程，可以发现一些问题，帮他解决。
• Cloudflare Pages 提供无限流量，推荐大家部署过去。

2026-04-03 09:42:00

最近科技圈有个热闹事：钉钉、飞书、企业微信，同一周全都开源了自己的 CLI。

你可能想问：CLI 是什么？跟之前老听到的 MCP 有什么关系？还有个叫 Skill 的又是什么？

别慌，今天用一个比喻把这三样东西讲明白。

先从一个场景说起

假设你是老板，刚招了一个超级能干的实习生（就是 AI Agent）。你想让他帮你在钉钉上干活：发消息、查日程、建表格、安排会议。

问题来了：实习生刚来，他不知道公司用什么工具，也不知道怎么操作。

你得解决三个问题：

1. 给他一个能操作钉钉的工具
2. 让他知道自己手边有这个工具
3. 教他什么场景用什么功能

这三个问题，分别对应的就是 CLI、MCP 和 Skill。

CLI：给实习生一套工具

CLI（Command Line Interface），命令行工具。就是你在电脑终端里敲一行文字，电脑帮你干活。

比如查今天的日程：

1

lark-cli calendar +agenda

比如给同事发条消息：

1

wecom-cli im send --text "周五下午开会" --to zhangsan

没有界面，没有按钮，全靠打字。

你可能觉得这也太原始了吧？但这恰恰是 AI 最喜欢的方式。因为 AI 最擅长处理文字，输入是文字、输出也是文字，非常对口。你让 AI 去操作图形界面，它得先截屏，再用视觉模型找按钮在哪，再模拟鼠标去点——本来一行命令搞定的事，拆成四步，每步都可能出错。

所以，CLI 就是实习生手里的工具箱。 扳手、螺丝刀、锤子，都在里面。他需要的时候拿出来用，不需要的时候放着就行。

MCP：在实习生桌上摆一排按钮

MCP（Model Context Protocol），模型上下文协议。名字唬人，但原理不复杂。

MCP 的做法是：提前把所有工具的说明贴在实习生桌上。”你能发消息””你能查日程””你能建表格”……每个能力做成一个按钮，实习生随时能按。

好处很明显：实习生不用四处找工具，一抬头就知道自己能干什么，直接按就行。

但有个代价：桌子就那么大。

AI 的”桌子”叫上下文窗口，大小是有限的。每个 MCP 工具都要在桌上摆一张说明卡。你接三五个工具，桌上还很宽敞。但你要是把钉钉、飞书、企业微信、GitHub、Slack、Jira 全接上，每个软件十几个功能，上百张说明卡往桌上一摊——桌子就被占满了，实习生连写字的地方都没有了。

而且工具太多还有个问题：实习生面对一百个按钮，选错的概率也会变大。

CLI 不一样。 工具箱放在柜子里，桌上不摆东西。需要的时候打开柜子拿出来用，用完放回去。桌子始终是干净的。当然代价是每次用之前得先翻一下工具箱看看有什么（跑个 --help），比直接按按钮慢了一步。

所以两者的核心区别就是：

• MCP = 工具常驻在桌上。 随取随用，但占桌面空间。工具少的时候很方便。
• CLI = 工具放在柜子里。 按需取用，不占桌面。工具多的时候更合适。

实际上，两者并不矛盾。钉钉和飞书都同时提供了 MCP 和 CLI 两种接入方式。能访问终端的环境（比如 Claude Code）用 CLI 更灵活，不能访问终端的环境（比如一些桌面端 AI 工具）就用 MCP。

Skill：给实习生一本操作手册

前面两个解决了”有什么工具”和”怎么让 AI 知道工具在哪”的问题。但还有一个问题：AI 知道有工具，不代表它会用好。

你跟 AI 说”帮我把会议纪要里的待办整理出来”，AI 得知道：先用什么命令读会议纪要？提取出来的待办该用什么命令创建？创建的时候需要哪些参数？出错了怎么办？

这就是 Skill 的作用——一本写给 AI 看的操作手册。

Skill 不是工具，它自己不干活。它告诉 AI：你有哪些命令可以用、什么场景该用哪个、参数怎么填、出了错怎么补救。

没有 Skill，AI 也能用 CLI，靠 --help 自己摸索。但这就像让新来的实习生自己翻工具箱说明书——能用，但慢，而且容易犯错。

有了 Skill，相当于给实习生一本经验丰富的老员工写的操作指南：”遇到查日程的需求，先用这个命令；如果对方没说时间范围，默认查本周；如果报权限错误，跑这个命令申请权限。”

实习生拿着这本手册，上手就快得多，犯错也少得多。

而且 Skill 的设计也很聪明——它跟 CLI 一样是按需加载的。AI 的上下文里只放一句话的简介：”你有一本操作钉钉的手册”。只有 AI 判断需要操作钉钉了，才会去翻开手册的详细内容。不用的时候，不占桌面空间。

三者的关系，一张图说清

1
2
3
4
5
6
7
8
9
10
11
12
13

你说一句话："帮我查下周跟张三的会议"
 │
 ▼
 AI 判断要操作日历
 │
 ▼
 Skill 告诉 AI 该用什么命令、参数怎么填
 │
 ▼
 AI 通过 CLI 在终端执行命令
 │
 ▼
 结果返回给你

• CLI 是手。 真正干活的。
• MCP 是另一种手。 也能干活，方式不同。
• Skill 是肌肉记忆。 让手知道该怎么动。

CLI 和 MCP 二选一（看环境支不支持终端），Skill 是加分项，有了它 AI 干活更靠谱。

那我作为普通用户需要关心这些吗？

说实话，大多数人不需要关心这些底层概念。

你真正会感受到的变化是：以后跟 AI 说一句话，它就能帮你操作钉钉、飞书、企业微信。查日程、发消息、建文档、排会议——你动嘴，AI 动手。

CLI、MCP、Skill，是让这件事成为可能的基础设施。就像你每天用微信，不需要知道 TCP/IP 协议怎么工作一样。

但如果你是那种喜欢搞清楚原理的人，记住这三句话就够了：

CLI 是给 AI 用的工具箱。
MCP 是把工具提前摆在 AI 桌上的一种方式。
Skill 是教 AI 怎么把工具用好的说明书。

过去的软件为人设计界面，现在的软件开始为 AI 设计接口。三大办公平台同一周开源 CLI，就是这个时代转变的一个缩影。

GUI 服务人类，CLI 服务 AI。同一个产品，两种形态，以后会是常态。