refactor: documents - regroup into principles/guides/case-studies

2026-08-23 15:58:05 +00:00 · 2026-02-28 06:50:35 +08:00
parent 5c341e0f71
commit e35529d8db
52 changed files with 0 additions and 0 deletions
@@ -0,0 +1,693 @@
+# AI 蜂群协作技术文档
+
+> 基于 tmux 的多 AI Agent 协作系统设计与实现
+
+---
+
+## 目录
+
+1. [核心思想](#1-核心思想)
+2. [技术原理](#2-技术原理)
+3. [命令参考](#3-命令参考)
+4. [协作协议](#4-协作协议)
+5. [架构模式](#5-架构模式)
+6. [实战案例](#6-实战案例)
+7. [提示词模板](#7-提示词模板)
+8. [最佳实践](#8-最佳实践)
+9. [风险与限制](#9-风险与限制)
+10. [扩展方向](#10-扩展方向)
+
+---
+
+## 1. 核心思想
+
+### 1.1 问题背景
+
+传统 AI 编程助手的局限：
+- 单一会话，无法感知其他任务
+- 遇到等待/确认时需要人工干预
+- 多任务并行时无法协调
+- 重复工作，资源浪费
+
+### 1.2 解决方案
+
+利用 tmux 的终端复用能力，赋予 AI：
+
+| 能力 | 实现方式 | 效果 |
+|:---|:---|:---|
+| **感知** | `capture-pane` | 读取任意终端内容 |
+| **控制** | `send-keys` | 向任意终端发送按键 |
+| **协调** | 共享状态文件 | 任务同步与分工 |
+
+### 1.3 核心洞察
+
+```
+传统模式: 人 ←→ AI₁, 人 ←→ AI₂, 人 ←→ AI₃ (人是瓶颈)
+
+蜂群模式: 人 → AI₁ ←→ AI₂ ←→ AI₃ (AI 自主协作)
+```
+
+**关键突破**：AI 不再是孤立的，而是可以互相感知、通讯、控制的集群。
+
+---
+
+## 2. 技术原理
+
+### 2.1 tmux 架构
+
+```
+┌─────────────────────────────────────────────┐
+│                 tmux server                  │
+├─────────────────────────────────────────────┤
+│  Session 0                                   │
+│  ├── Window 0:1 [AI-1] ◄──┐                 │
+│  ├── Window 0:2 [AI-2] ◄──┼── 互相可见/控制 │
+│  ├── Window 0:3 [AI-3] ◄──┤                 │
+│  └── Window 0:4 [AI-4] ◄──┘                 │
+└─────────────────────────────────────────────┘
+```
+
+### 2.2 数据流
+
+```
+┌─────────┐  capture-pane   ┌─────────┐
+│  AI-1   │ ◄───────────────│  AI-4   │
+│ (执行)  │                 │ (监控)  │
+└─────────┘  send-keys      └─────────┘
+     ▲      ───────────────►     │
+     │                           │
+     └───────── 控制流 ──────────┘
+```
+
+### 2.3 通信机制
+
+| 机制 | 方向 | 延迟 | 用途 |
+|:---|:---|:---|:---|
+| `capture-pane` | 读取 | 即时 | 获取终端输出 |
+| `send-keys` | 写入 | 即时 | 发送命令/按键 |
+| 共享文件 | 双向 | 文件IO | 状态持久化 |
+
+---
+
+## 3. 命令参考
+
+### 3.1 信息获取
+
+```bash
+# 列出所有会话
+tmux list-sessions
+
+# 列出所有窗口
+tmux list-windows -a
+
+# 列出所有窗格
+tmux list-panes -a
+
+# 获取当前窗口标识
+echo $TMUX_PANE
+```
+
+### 3.2 内容读取
+
+```bash
+# 读取指定窗口内容（最近 N 行）
+tmux capture-pane -t <session>:<window> -p -S -<N>
+
+# 示例：读取会话 0 窗口 1 最近 100 行
+tmux capture-pane -t 0:1 -p -S -100
+
+# 读取并保存到文件
+tmux capture-pane -t 0:1 -p -S -500 > /tmp/window1.log
+
+# 批量读取所有窗口
+for w in $(tmux list-windows -a -F '#{session_name}:#{window_index}'); do
+  echo "=== $w ==="
+  tmux capture-pane -t "$w" -p -S -30
+done
+```
+
+### 3.3 发送控制
+
+```bash
+# 发送文本 + 回车
+tmux send-keys -t 0:1 "ls -la" Enter
+
+# 发送确认
+tmux send-keys -t 0:1 "y" Enter
+
+# 发送特殊按键
+tmux send-keys -t 0:1 C-c        # Ctrl+C
+tmux send-keys -t 0:1 C-d        # Ctrl+D
+tmux send-keys -t 0:1 C-z        # Ctrl+Z
+tmux send-keys -t 0:1 Escape     # ESC
+tmux send-keys -t 0:1 Up         # 上箭头
+tmux send-keys -t 0:1 Down       # 下箭头
+tmux send-keys -t 0:1 Tab        # Tab
+
+# 组合操作
+tmux send-keys -t 0:1 C-c        # 先中断
+tmux send-keys -t 0:1 "cd /tmp" Enter  # 再执行新命令
+```
+
+### 3.4 窗口管理
+
+```bash
+# 创建新窗口
+tmux new-window -n "ai-worker"
+
+# 创建并执行命令
+tmux new-window -n "ai-1" "kiro-cli chat"
+
+# 关闭窗口
+tmux kill-window -t 0:1
+
+# 重命名窗口
+tmux rename-window -t 0:1 "monitor"
+```
+
+---
+
+## 4. 协作协议
+
+### 4.1 状态定义
+
+```bash
+# 状态文件位置
+/tmp/ai_swarm/
+├── status.log      # 全局状态日志
+├── tasks.json      # 任务队列
+├── locks/          # 任务锁
+│   ├── task_001.lock
+│   └── task_002.lock
+└── results/        # 结果存储
+    ├── ai_1.json
+    └── ai_2.json
+```
+
+### 4.2 状态格式
+
+```bash
+# 状态日志格式
+[HH:MM:SS] [窗口ID] [状态] 描述
+
+# 示例
+[08:15:30] [0:1] [START] 开始处理 data-service 代码审计
+[08:16:45] [0:1] [DONE] 完成代码审计，发现 5 个问题
+[08:16:50] [0:2] [WAIT] 等待 0:1 审计结果
+[08:17:00] [0:2] [START] 开始修复问题
+```
+
+### 4.3 协作规则
+
+| 规则 | 描述 | 实现 |
+|:---|:---|:---|
+| **先查后做** | 开始前扫描其他终端 | `capture-pane` 全扫 |
+| **避免冲突** | 相同任务只做一次 | 检查 locks 目录 |
+| **主动救援** | 发现卡住主动帮助 | 检测 `[y/n]` 等待 |
+| **状态广播** | 完成后通知其他 AI | 写入 status.log |
+
+### 4.4 冲突处理
+
+```
+场景：AI-1 和 AI-2 同时要修改同一文件
+
+解决方案：
+1. 创建任务前先检查锁
+2. 获取锁后才能执行
+3. 完成后释放锁
+
+# 获取锁
+if [ ! -f /tmp/ai_swarm/locks/file_x.lock ]; then
+  echo "$TMUX_PANE" > /tmp/ai_swarm/locks/file_x.lock
+  # 执行任务
+  rm /tmp/ai_swarm/locks/file_x.lock
+fi
+```
+
+---
+
+## 5. 架构模式
+
+### 5.1 对等模式 (P2P)
+
+```
+┌─────┐     ┌─────┐
+│ AI₁ │◄───►│ AI₂ │
+└──┬──┘     └──┬──┘
+   │           │
+   ▼           ▼
+┌─────┐     ┌─────┐
+│ AI₃ │◄───►│ AI₄ │
+└─────┘     └─────┘
+
+特点：所有 AI 平等，互相监控
+适用：简单任务，无明确依赖
+```
+
+### 5.2 主从模式 (Master-Worker)
+
+```
+        ┌──────────┐
+        │ AI-Master│
+        │  (指挥官) │
+        └────┬─────┘
+             │ 分发/监控
+    ┌────────┼────────┐
+    ▼        ▼        ▼
+┌──────┐ ┌──────┐ ┌──────┐
+│Worker│ │Worker│ │Worker│
+│ AI-1 │ │ AI-2 │ │ AI-3 │
+└──────┘ └──────┘ └──────┘
+
+特点：一个指挥，多个执行
+适用：复杂项目，需要统一协调
+```
+
+### 5.3 流水线模式 (Pipeline)
+
+```
+┌─────┐    ┌─────┐    ┌─────┐    ┌─────┐
+│ AI₁ │───►│ AI₂ │───►│ AI₃ │───►│ AI₄ │
+│分析 │    │设计 │    │实现 │    │测试 │
+└─────┘    └─────┘    └─────┘    └─────┘
+
+特点：任务串行流转
+适用：有明确阶段的工作流
+```
+
+### 5.4 混合模式
+
+```
+           ┌──────────┐
+           │ AI-Master│
+           └────┬─────┘
+                │
+    ┌───────────┼───────────┐
+    ▼           ▼           ▼
+┌──────┐   ┌──────┐    ┌──────┐
+│分析组 │   │开发组 │    │测试组 │
+├──────┤   ├──────┤    ├──────┤
+│AI-1  │   │AI-3  │    │AI-5  │
+│AI-2  │   │AI-4  │    │AI-6  │
+└──────┘   └──────┘    └──────┘
+
+特点：分组协作 + 统一调度
+适用：大型项目，多团队并行
+```
+
+---
+
+## 6. 实战案例
+
+### 6.1 案例：多服务并行开发
+
+**场景**：同时开发 data-service、trading-service、telegram-service
+
+**配置**：
+```bash
+# 窗口分配
+0:1 - AI-Master (指挥官)
+0:2 - AI-Data (data-service)
+0:3 - AI-Trading (trading-service)
+0:4 - AI-Telegram (telegram-service)
+```
+
+**指挥官提示词**：
+```
+你是项目指挥官，负责协调 3 个开发 AI。
+
+每 2 分钟执行一次扫描：
+for w in 2 3 4; do
+  echo "=== 窗口 0:$w ===" 
+  tmux capture-pane -t "0:$w" -p -S -20
+done
+
+发现问题时：
+- 卡住等待 → send-keys 确认
+- 报错 → 分析并给出建议
+- 完成 → 记录并分配下一任务
+```
+
+### 6.2 案例：代码审计 + 自动修复
+
+**场景**：AI-1 审计代码，AI-2 实时修复
+
+**流程**：
+```
+AI-1 (审计):
+1. 扫描代码，输出问题列表
+2. 每发现一个问题，写入 /tmp/ai_swarm/issues.log
+
+AI-2 (修复):
+1. 监控 issues.log
+2. 读取新问题
+3. 自动修复
+4. 标记完成
+```
+
+### 6.3 案例：7x24 值守
+
+**场景**：AI 互相监控，自动救援
+
+**配置**：
+```bash
+# 每个 AI 的监控逻辑
+while true; do
+  for w in $(tmux list-windows -a -F '#{window_index}'); do
+    output=$(tmux capture-pane -t "0:$w" -p -S -5)
+    
+    # 检测卡住
+    if echo "$output" | grep -q "\[y/n\]"; then
+      tmux send-keys -t "0:$w" "y" Enter
+      echo "已帮助窗口 $w 确认"
+    fi
+    
+    # 检测错误
+    if echo "$output" | grep -qi "error\|failed"; then
+      echo "窗口 $w 出现错误，需要关注"
+    fi
+  done
+  sleep 30
+done
+```
+
+---
+
+## 7. 提示词模板
+
+### 7.1 基础版（Worker）
+
+```markdown
+## AI 蜂群协作模式
+
+你在 tmux 环境中工作，可以感知和协助其他终端。
+
+### 命令
+# 扫描所有终端
+tmux list-windows -a
+
+# 读取终端内容
+tmux capture-pane -t <session>:<window> -p -S -100
+
+### 行为
+- 开始任务前先扫描环境
+- 发现相关任务主动协调
+- 完成后广播状态
+```
+
+### 7.2 完整版（Worker）
+
+```markdown
+## 🐝 AI 蜂群协作协议 v2.0
+
+你是 tmux 多终端 AI 集群中的一员。
+
+### 感知能力
+
+# 列出所有窗口
+tmux list-windows -a
+
+# 读取指定窗口（最近 100 行）
+tmux capture-pane -t <session>:<window> -p -S -100
+
+# 批量扫描
+for w in $(tmux list-windows -a -F '#{session_name}:#{window_index}'); do
+  echo "=== $w ===" && tmux capture-pane -t "$w" -p -S -20
+done
+
+### 控制能力
+
+# 发送命令
+tmux send-keys -t <窗口> "<命令>" Enter
+
+# 发送确认
+tmux send-keys -t <窗口> "y" Enter
+
+# 中断任务
+tmux send-keys -t <窗口> C-c
+
+### 协作规则
+
+1. **主动感知**：任务开始前扫描其他终端
+2. **避免冲突**：相同任务不重复执行
+3. **主动救援**：发现等待/卡住主动帮助
+4. **状态广播**：完成后写入共享日志
+
+### 状态同步
+
+# 广播
+echo "[$(date +%H:%M:%S)] [$TMUX_PANE] [DONE] <描述>" >> /tmp/ai_swarm/status.log
+
+# 读取
+tail -20 /tmp/ai_swarm/status.log
+
+### 检查时机
+
+- 🚦 任务开始前
+- ⏳ 等待依赖时
+- ✅ 任务完成后
+- ❌ 遇到错误时
+```
+
+### 7.3 指挥官版（Master）
+
+```markdown
+## 🎖️ AI 集群指挥官协议
+
+你是 AI 蜂群的指挥官，负责监控和协调所有 Worker AI。
+
+### 核心职责
+
+1. **全局监控**：定期扫描所有终端状态
+2. **任务分配**：根据能力分配任务
+3. **冲突解决**：发现重复工作时协调
+4. **故障救援**：发现卡住/错误时介入
+5. **进度汇总**：汇总各终端成果
+
+### 监控命令
+
+# 全局扫描（每 2 分钟执行）
+echo "========== $(date) 状态扫描 =========="
+for w in $(tmux list-windows -a -F '#{session_name}:#{window_index}'); do
+  echo "--- $w ---"
+  tmux capture-pane -t "$w" -p -S -15
+done
+
+### 干预命令
+
+# 帮助确认
+tmux send-keys -t <窗口> "y" Enter
+
+# 中断错误任务
+tmux send-keys -t <窗口> C-c
+
+# 发送新指令
+tmux send-keys -t <窗口> "<指令>" Enter
+
+### 状态判断
+
+检测到以下模式时介入：
+- `[y/n]` `[Y/n]` `确认` → 需要确认
+- `Error` `Failed` `Exception` → 出现错误
+- `Waiting` `Blocked` → 任务阻塞
+- 长时间无输出 → 可能卡死
+
+### 汇报格式
+
+每次扫描后输出：
+| 窗口 | 状态 | 当前任务 | 备注 |
+|:---|:---|:---|:---|
+| 0:1 | ✅ 正常 | 代码审计 | 进度 80% |
+| 0:2 | ⏳ 等待 | 等待确认 | 已自动确认 |
+| 0:3 | ❌ 错误 | 编译失败 | 需要关注 |
+```
+
+---
+
+## 8. 最佳实践
+
+### 8.1 初始化流程
+
+```bash
+# 1. 创建共享目录
+mkdir -p /tmp/ai_swarm/{locks,results}
+touch /tmp/ai_swarm/status.log
+
+# 2. 开启 tmux 会话
+tmux new-session -d -s ai
+
+# 3. 创建多个窗口
+tmux new-window -t ai -n "master"
+tmux new-window -t ai -n "worker-1"
+tmux new-window -t ai -n "worker-2"
+tmux new-window -t ai -n "worker-3"
+
+# 4. 在每个窗口启动 AI
+tmux send-keys -t ai:master "kiro-cli chat" Enter
+tmux send-keys -t ai:worker-1 "kiro-cli chat" Enter
+# ...
+
+# 5. 发送蜂群提示词
+```
+
+### 8.2 命名规范
+
+```bash
+# 会话命名
+ai          # AI 工作会话
+dev         # 开发会话
+monitor     # 监控会话
+
+# 窗口命名
+master      # 指挥官
+worker-N    # 工作节点
+data        # data-service 专用
+trading     # trading-service 专用
+```
+
+### 8.3 日志规范
+
+```bash
+# 状态日志
+[时间] [窗口] [状态] 描述
+
+# 状态类型
+[START]  - 开始任务
+[DONE]   - 完成任务
+[WAIT]   - 等待中
+[ERROR]  - 出现错误
+[HELP]   - 请求帮助
+[SKIP]   - 跳过（已有人处理）
+```
+
+### 8.4 安全建议
+
+1. **不要自动确认危险操作**：rm -rf、DROP TABLE 等
+2. **设置操作白名单**：只允许特定命令
+3. **保留操作日志**：记录所有 send-keys 操作
+4. **定期人工检查**：不要完全无人值守
+
+---
+
+## 9. 风险与限制
+
+### 9.1 已知风险
+
+| 风险 | 描述 | 缓解措施 |
+|:---|:---|:---|
+| 误操作 | AI 发送错误命令 | 设置命令白名单 |
+| 死循环 | AI 互相触发 | 添加冷却时间 |
+| 资源竞争 | 同时修改同一文件 | 使用锁机制 |
+| 信息泄露 | 敏感信息被读取 | 隔离敏感会话 |
+
+### 9.2 技术限制
+
+- tmux 必须在同一服务器
+- 无法跨机器协作（需要 SSH）
+- 终端输出有长度限制
+- 无法读取密码输入（隐藏字符）
+
+### 9.3 不适用场景
+
+- 需要图形界面的操作
+- 涉及敏感凭证的操作
+- 需要实时交互的场景
+- 跨网络的分布式协作
+
+---
+
+## 10. 扩展方向
+
+### 10.1 跨机器协作
+
+```bash
+# 通过 SSH 读取远程 tmux
+ssh user@remote "tmux capture-pane -t 0:1 -p"
+
+# 通过 SSH 发送命令
+ssh user@remote "tmux send-keys -t 0:1 'ls' Enter"
+```
+
+### 10.2 Web 监控面板
+
+```python
+# 简单的状态 API
+from flask import Flask, jsonify
+import subprocess
+
+app = Flask(__name__)
+
+@app.route('/status')
+def status():
+    result = subprocess.run(
+        ['tmux', 'list-windows', '-a', '-F', '#{window_name}:#{window_activity}'],
+        capture_output=True, text=True
+    )
+    return jsonify({'windows': result.stdout.split('\n')})
+```
+
+### 10.3 智能调度
+
+```python
+# 基于负载的任务分配
+def assign_task(task):
+    windows = get_all_windows()
+    
+    # 找到最空闲的窗口
+    idle_window = min(windows, key=lambda w: w.activity_time)
+    
+    # 分配任务
+    send_keys(idle_window, f"处理任务: {task}")
+```
+
+### 10.4 与其他系统集成
+
+- **Slack/Discord**：状态通知
+- **Prometheus**：指标监控
+- **Grafana**：可视化面板
+- **GitHub Actions**：CI/CD 触发
+
+---
+
+## 附录
+
+### A. 快速参考卡片
+
+```
+┌─────────────────────────────────────────────────────┐
+│              AI 蜂群命令速查                         │
+├─────────────────────────────────────────────────────┤
+│ 列出窗口    tmux list-windows -a                    │
+│ 读取内容    tmux capture-pane -t 0:1 -p -S -100     │
+│ 发送命令    tmux send-keys -t 0:1 "cmd" Enter       │
+│ 发送确认    tmux send-keys -t 0:1 "y" Enter         │
+│ 中断任务    tmux send-keys -t 0:1 C-c               │
+│ 新建窗口    tmux new-window -n "name"               │
+└─────────────────────────────────────────────────────┘
+```
+
+### B. 故障排查
+
+```bash
+# tmux 不存在
+which tmux || sudo apt install tmux
+
+# 无法连接会话
+tmux list-sessions  # 检查会话是否存在
+
+# capture-pane 无输出
+tmux capture-pane -t 0:1 -p -S -1000  # 增加行数
+
+# send-keys 无效
+tmux display-message -t 0:1 -p '#{pane_mode}'  # 检查模式
+```
+
+### C. 参考资料
+
+- tmux 官方文档: https://github.com/tmux/tmux/wiki
+- tmux 命令速查: `man tmux`
+
+---
+
+*文档版本: v1.0*
+*最后更新: 2026-01-04*
@@ -0,0 +1,60 @@
+# Gemini 无头模式 JSONL 规范化指引
+
+目标：在本地使用 Gemini CLI（gemini-2.5-flash）批量将提示词内容转换为标准 JSONL（`{"title": "...", "content": "..."}`），全程无交互、禁止工具调用，输出可直接落盘。
+
+## 工作原理
+- Gemini CLI 无独立 system slot，使用“位置参数 prompt”承载系统提示词；待处理文本通过 stdin 传入。
+- 通过 `--allowed-tools ''` 关闭工具调用，确保只返回模型文本。
+- 选用 `--output-format text`，配合系统提示词的“纯 JSONL 输出”约束，得到一行一个 JSON 对象。
+- 代理变量可选（`http_proxy/https_proxy`），按实际网络需要设置。
+
+## 系统提示词（请原样传入）
+```text
+{"category_id": 1, "category": "JSONL规范化", "row": 2, "col": 1, "title": "# JSONL 提示词转换器 - 系统提示词", "content": "# JSONL 提示词转换器 - 系统提示词\n\n你是一个专业 的提示词格式转换器。将用户提供的提示词内容转换为标准 JSONL 格式。\n\n## 输出格式\n\n```json\n{\"title\": \"<标题>\", \"content\": \"<完整内容>\"}\n```\n\n### 字段说明\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `title` | string | 提示词标题，取内容的第一行或前 50 字符 |\n| `content` | string | 完整的提示词内容 |\n\n## 转换规则\n\n1. **标题提取**：\n   - 若内容以 `#` 开头，取第一个标题作为 title\n   - 否则取前 50 字符（去除换行）\n2. **内容转义**：\n   - 换行符 转为 `\\n`\n   - 双引号转为 `\\\"`\n   - 反斜杠转为 `\\\\`\n\n## 输出要求\n\n- 每行一个完整的 JSON 对象\n- 不要添加任何解释、注释或额外文字\n- 不要用 ```json 代码块包裹\n- 直接输出纯 JSONL 内容\n\n## 示例\n\n### 输入\n```\n# Role：智能文档助手\n\n## Background\n用户需要一个能够处理文档的 AI 助手。\n\n## Skills\n-  文档解析\n- 格式转换\n```\n\n### 输出\n```\n{\"title\": \"# Role：智能文档助手\", \"content\": \"# Role：智能文档助手\\n\\n## Background\\n用户需要一个能够处 理文档的 AI 助手。\\n\\n## Skills\\n- 文档解析\\n- 格式转换\"}\n```\n\n---\n\n现在，请将用户提供的内容转换为标准 JSONL 格式。"}
+```
+
+## 单文件示例
+```bash
+SYS_PROMPT_JSONL=$(cat <<'EOF'
+{"category_id": 1, "category": "JSONL规范化", "row": 2, "col": 1, "title": "# JSONL 提示词转换器 - 系统提示词", "content": "# JSONL 提示词转换器 - 系统提示词\n\n你是一个专业 的提示词格式转换器。将用户提供的提示词内容转换为标准 JSONL 格式。\n\n## 输出格式\n\n```json\n{\"title\": \"<标题>\", \"content\": \"<完整内容>\"}\n```\n\n### 字段说明\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `title` | string | 提示词标题，取内容的第一行或前 50 字符 |\n| `content` | string | 完整的提示词内容 |\n\n## 转换规则\n\n1. **标题提取**：\n   - 若内容以 `#` 开头，取第一个标题作为 title\n   - 否则取前 50 字符（去除换行）\n2. **内容转义**：\n   - 换行符 转为 `\\n`\n   - 双引号转为 `\\\"`\n   - 反斜杠转为 `\\\\`\n\n## 输出要求\n\n- 每行一个完整的 JSON 对象\n- 不要添加任何解释、注释或额外文字\n- 不要用 ```json 代码块包裹\n- 直接输出纯 JSONL 内容\n\n## 示例\n\n### 输入\n```\n# Role：智能文档助手\n\n## Background\n用户需要一个能够处理文档的 AI 助手。\n\n## Skills\n-  文档解析\n- 格式转换\n```\n\n### 输出\n```\n{\"title\": \"# Role：智能文档助手\", \"content\": \"# Role：智能文档助手\\n\\n## Background\\n用户需要一个能够处 理文档的 AI 助手。\\n\\n## Skills\\n- 文档解析\\n- 格式转换\"}\n```\n\n---\n\n现在，请将用户提供的内容转换为标准 JSONL 格式。"}
+EOF
+)
+
+# 单条转换（stdin 输入提示词内容，stdout 得到单行 JSON）
+cat 2/ASCII图生成.md | gemini -m gemini-2.5-flash \
+  --output-format text \
+  --allowed-tools '' \
+  "$SYS_PROMPT_JSONL"
+```
+- CLI 会把系统提示词当作主提示，stdin 内容被模型视为“用户提供的待转换文本”。
+- 若需要代理，可在命令前设置 `http_proxy/https_proxy`。
+
+## 批量处理目录 `2/` → 生成 `2/prompts.jsonl`
+```bash
+SYS_PROMPT_JSONL=... # 同上
+out=2/prompts.jsonl
+: > "$out"
+for f in 2/*.md; do
+  [ -f "$f" ] || continue
+  cat "$f" | gemini -m gemini-2.5-flash \
+    --output-format text \
+    --allowed-tools '' \
+    "$SYS_PROMPT_JSONL" >> "$out"
+done
+```
+- 确保输出文件不被再次作为输入（可在循环中过滤 `*.jsonl`）。
+- 完成后可用 `wc -l 2/prompts.jsonl` 验证行数应等于处理的文件数。
+
+## 质量校验清单
+- 每行必须是合法 JSON，对象包含 `title` 与 `content` 两个字段。
+- 不得出现额外解释、空行或代码块定界符。
+- `title` 取首个 `#` 标题或去除换行后的前 50 字符；`content` 保留原文并正确转义。
+- 建议随机抽查 2–3 行，确认换行、引号、反斜杠均被转义为 `\\n` / `\\\"` / `\\\\`。
+
+## 常见故障
+- **输出混入 CLI 提示或日志**：确保命令中未开启 `--debug`，并避免在循环内打印 stdout。
+- **代理导致失败**：移除 `http_proxy/https_proxy` 或改用本地直连后重试。
+- **行数不匹配**：检查是否循环中包含 `*.jsonl` 自身或隐藏文件，必要时改为 `for f in 2/*.md; do ...; done`。
+
+## 已生成的基线文件
+- 运行批量脚本后，本仓库已生成 `2/prompts.jsonl`，涵盖 `2/` 目录下所有 `.md` 提示词，可直接复用或作为后续增量基线。
@@ -0,0 +1,169 @@
+# LazyVim 快捷键大全
+
+| 快捷键 | 功能 |
+|--------|------|
+| **通用** ||
+| `<Space>` 等1秒 | 显示快捷键菜单 |
+| `<Space>sk` | 搜索所有快捷键 |
+| `u` | 撤销 |
+| `Ctrl+r` | 重做 |
+| `.` | 重复上次操作 |
+| `Esc` | 退出插入模式/取消 |
+| **文件** ||
+| `<Space>ff` | 搜索文件 |
+| `<Space>fr` | 最近打开的文件 |
+| `<Space>fn` | 新建文件 |
+| `<Space>fs` | 保存文件 |
+| `<Space>fS` | 另存为 |
+| `<Space>e` | 打开/关闭侧边栏 |
+| `<Space>E` | 侧边栏定位当前文件 |
+| **搜索** ||
+| `<Space>sg` | 全局搜索文本 (grep) |
+| `<Space>sw` | 搜索光标下的词 |
+| `<Space>sb` | 当前 buffer 搜索 |
+| `<Space>ss` | 搜索符号 |
+| `<Space>sS` | 工作区搜索符号 |
+| `<Space>sh` | 搜索帮助文档 |
+| `<Space>sm` | 搜索标记 |
+| `<Space>sr` | 搜索替换 |
+| `/` | 当前文件搜索 |
+| `n` | 下一个搜索结果 |
+| `N` | 上一个搜索结果 |
+| `*` | 搜索光标下的词 |
+| **Buffer（标签页）** ||
+| `Shift+h` | 上一个 buffer |
+| `Shift+l` | 下一个 buffer |
+| `<Space>bb` | 切换到其他 buffer |
+| `<Space>bd` | 关闭当前 buffer |
+| `<Space>bD` | 强制关闭 buffer |
+| `<Space>bo` | 关闭其他 buffer |
+| `<Space>bp` | 固定 buffer |
+| `<Space>bl` | 删除左侧 buffer |
+| `<Space>br` | 删除右侧 buffer |
+| `[b` | 上一个 buffer |
+| `]b` | 下一个 buffer |
+| **窗口/分屏** ||
+| `Ctrl+h` | 移动到左边窗口 |
+| `Ctrl+j` | 移动到下边窗口 |
+| `Ctrl+k` | 移动到上边窗口 |
+| `Ctrl+l` | 移动到右边窗口 |
+| `<Space>-` | 水平分屏 |
+| `<Space>\|` | 垂直分屏 |
+| `<Space>wd` | 关闭当前窗口 |
+| `<Space>ww` | 切换窗口 |
+| `<Space>wo` | 关闭其他窗口 |
+| `Ctrl+Up` | 增加窗口高度 |
+| `Ctrl+Down` | 减少窗口高度 |
+| `Ctrl+Left` | 减少窗口宽度 |
+| `Ctrl+Right` | 增加窗口宽度 |
+| **终端** ||
+| `Ctrl+/` | 浮动终端 |
+| `<Space>ft` | 浮动终端 |
+| `<Space>fT` | 当前目录终端 |
+| `Ctrl+\` | 退出终端模式 |
+| **代码导航** ||
+| `gd` | 跳转到定义 |
+| `gD` | 跳转到声明 |
+| `gr` | 查看引用 |
+| `gI` | 跳转到实现 |
+| `gy` | 跳转到类型定义 |
+| `K` | 查看文档悬浮窗 |
+| `gK` | 签名帮助 |
+| `Ctrl+k` | 插入模式签名帮助 |
+| `]d` | 下一个诊断 |
+| `[d` | 上一个诊断 |
+| `]e` | 下一个错误 |
+| `[e` | 上一个错误 |
+| `]w` | 下一个警告 |
+| `[w` | 上一个警告 |
+| **代码操作** ||
+| `<Space>ca` | 代码操作 |
+| `<Space>cA` | 源代码操作 |
+| `<Space>cr` | 重命名 |
+| `<Space>cf` | 格式化文件 |
+| `<Space>cd` | 行诊断信息 |
+| `<Space>cl` | LSP 信息 |
+| `<Space>cm` | Mason (管理 LSP) |
+| **注释** ||
+| `gcc` | 注释/取消注释当前行 |
+| `gc` | 注释选中区域 |
+| `gco` | 下方添加注释 |
+| `gcO` | 上方添加注释 |
+| `gcA` | 行尾添加注释 |
+| **Git** ||
+| `<Space>gg` | 打开 lazygit |
+| `<Space>gG` | 当前目录 lazygit |
+| `<Space>gf` | git 文件列表 |
+| `<Space>gc` | git 提交记录 |
+| `<Space>gs` | git 状态 |
+| `<Space>gb` | git blame 当前行 |
+| `<Space>gB` | 浏览器打开仓库 |
+| `]h` | 下一个 git 修改块 |
+| `[h` | 上一个 git 修改块 |
+| `<Space>ghp` | 预览修改块 |
+| `<Space>ghs` | 暂存修改块 |
+| `<Space>ghr` | 重置修改块 |
+| `<Space>ghS` | 暂存整个文件 |
+| `<Space>ghR` | 重置整个文件 |
+| `<Space>ghd` | diff 当前文件 |
+| **选择/编辑** ||
+| `v` | 进入可视模式 |
+| `V` | 行选择模式 |
+| `Ctrl+v` | 块选择模式 |
+| `y` | 复制 |
+| `d` | 删除/剪切 |
+| `p` | 粘贴 |
+| `P` | 在前面粘贴 |
+| `c` | 修改 |
+| `x` | 删除字符 |
+| `r` | 替换字符 |
+| `~` | 切换大小写 |
+| `>>` | 增加缩进 |
+| `<<` | 减少缩进 |
+| `=` | 自动缩进 |
+| `J` | 合并行 |
+| **移动** ||
+| `h/j/k/l` | 左/下/上/右 |
+| `w` | 下一个词首 |
+| `b` | 上一个词首 |
+| `e` | 下一个词尾 |
+| `0` | 行首 |
+| `$` | 行尾 |
+| `^` | 行首非空字符 |
+| `gg` | 文件开头 |
+| `G` | 文件末尾 |
+| `{` | 上一个段落 |
+| `}` | 下一个段落 |
+| `%` | 匹配括号跳转 |
+| `Ctrl+d` | 向下半页 |
+| `Ctrl+u` | 向上半页 |
+| `Ctrl+f` | 向下一页 |
+| `Ctrl+b` | 向上一页 |
+| `zz` | 当前行居中 |
+| `zt` | 当前行置顶 |
+| `zb` | 当前行置底 |
+| `数字+G` | 跳转到指定行 |
+| **折叠** ||
+| `za` | 切换折叠 |
+| `zA` | 递归切换折叠 |
+| `zo` | 打开折叠 |
+| `zc` | 关闭折叠 |
+| `zR` | 打开所有折叠 |
+| `zM` | 关闭所有折叠 |
+| **UI** ||
+| `<Space>uf` | 切换格式化 |
+| `<Space>us` | 切换拼写检查 |
+| `<Space>uw` | 切换自动换行 |
+| `<Space>ul` | 切换行号 |
+| `<Space>uL` | 切换相对行号 |
+| `<Space>ud` | 切换诊断 |
+| `<Space>uc` | 切换隐藏字符 |
+| `<Space>uh` | 切换高亮 |
+| `<Space>un` | 关闭通知 |
+| **退出** ||
+| `<Space>qq` | 退出全部 |
+| `<Space>qQ` | 强制退出全部 |
+| `:w` | 保存 |
+| `:q` | 退出 |
+| `:wq` | 保存并退出 |
+| `:q!` | 强制退出不保存 |
@@ -0,0 +1,28 @@
+# 🛠️ 方法论
+
+> 工具使用、开发经验与实践技巧
+
+## 🎨 AI 协作范式
+
+- [Canvas白板驱动开发](./图形化AI协作-Canvas白板驱动开发.md) - 图形是第一公民，代码是白板的序列化形式
+- [AI蜂群协作](./AI蜂群协作-tmux多Agent协作系统.md) - 基于 tmux 的多 AI Agent 协作系统
+
+## 📖 工具教程
+
+- [tmux 快捷键大全](./tmux快捷键大全.md) - 终端复用工具
+- [LazyVim 快捷键大全](./LazyVim快捷键大全.md) - Neovim 配置框架
+- [Augment MCP 配置](./auggie-mcp配置文档.md) - 上下文引擎配置
+- [ProxyCast 配置](./ProxyCast配置文档.md) - AI 凭证代理服务配置
+- [手机远程 Vibe Coding](./关于手机ssh任意位置链接本地计算机，基于frp实现的方法.md) - 基于 frp 的远程开发
+- [VS Code Remote Tunnel（WSL）](./REMOTE_TUNNEL_GUIDE.md) - 在 WSL 内开通 VS Code Tunnel 供远程访问
+- [GEMINI-HEADLESS](./GEMINI-HEADLESS.md) - Gemini 无头模式配置
+
+## 🛠️ 开发经验
+
+- [开发经验](./开发经验.md) - 变量命名、文件结构、编码规范
+- [Vibe Coding 经验收集](./vibe-coding-经验收集.md) - 社区经验汇总
+
+## 🔗 相关资源
+- [基础指南](../00-基础指南/) - 核心理念与方法论
+- [入门指南](../01-入门指南/) - 从零开始
+- [实战](../03-实战/) - 动手实践
@@ -0,0 +1,67 @@
+# VS Code Remote Tunnel（WSL 侧）快速指南
+
+面向场景：在 WSL 内开通 VS Code Tunnel，供 Mac/任意客户端通过 Remote - Tunnels 或 vscode.dev 访问。
+
+## 前置条件
+- WSL 已开启 systemd（`/etc/wsl.conf` 有 `[boot] systemd=true`，然后 `wsl --shutdown` 重进）。
+- 网络可直连或通过本机代理 127.0.0.1:9910（本指南示例端口）。
+
+## 安装 VS Code CLI（WSL 内）
+```bash
+sudo apt-get update
+sudo apt-get install -y wget gpg apt-transport-https
+wget -qO- https://packages.microsoft.com/keys/microsoft.asc | gpg --dearmor | sudo tee /etc/apt/keyrings/packages.microsoft.gpg >/dev/null
+echo "deb [arch=amd64,arm64 signed-by=/etc/apt/keyrings/packages.microsoft.gpg] https://packages.microsoft.com/repos/code stable main" | sudo tee /etc/apt/sources.list.d/vscode.list
+sudo apt-get update
+sudo apt-get install -y code
+which code   # 应为 /usr/local/bin/code 或 /usr/bin/code
+```
+
+## 一次性登录
+```bash
+/usr/local/bin/code tunnel user login
+# 浏览器打开提示的 device code 完成 GitHub 授权
+```
+
+## 配置代理（可选，示例 127.0.0.1:9910）
+创建 drop-in：
+```bash
+mkdir -p ~/.config/systemd/user/code-tunnel.service.d
+cat > ~/.config/systemd/user/code-tunnel.service.d/proxy.conf <<'EOF'
+[Service]
+Environment=HTTP_PROXY=http://127.0.0.1:9910
+Environment=HTTPS_PROXY=http://127.0.0.1:9910
+Environment=NO_PROXY=localhost,127.0.0.1,::1
+EOF
+systemctl --user daemon-reload
+```
+
+## 安装并开机自启隧道服务
+```bash
+/usr/local/bin/code tunnel service install --accept-server-license-terms --name wsl-lenovo
+systemctl --user enable code-tunnel.service
+systemctl --user restart code-tunnel.service
+```
+
+## 验证
+```bash
+/usr/local/bin/code tunnel status        # tunnel: Connected 且 service_installed:true
+systemctl --user status code-tunnel.service --no-pager
+```
+
+## 客户端连接
+- VS Code 桌面：安装 “Remote - Tunnels”，用同一 GitHub 账号登录，Remote Explorer 选择 `wsl-lenovo`。
+- 纯浏览器：访问 `https://vscode.dev/tunnel/wsl-lenovo`，同账号登录即可。
+
+## 日志与维护
+```bash
+/usr/local/bin/code tunnel service log --log info   # 查看服务日志
+/usr/local/bin/code tunnel rename <new-name>        # 重命名隧道
+/usr/local/bin/code tunnel kill                     # 停止当前隧道进程
+/usr/local/bin/code tunnel service uninstall        # 移除自启服务
+```
+
+## 常见故障排查
+- 仍显示 Disconnected：确认代理可用，`curl https://api.github.com` 能通；或暂时 `unset HTTP_PROXY HTTPS_PROXY` 再试。
+- 路径错误 (`\\wsl.localhost\\...`)：不要在 `terminal.integrated.cwd` 写 UNC，删除该项或用 POSIX 路径。
+- 未启用 systemd：检查 `/etc/wsl.conf`，修改后 `wsl --shutdown` 重新进入。
@@ -0,0 +1,147 @@
+# auggie-mcp 详细配置文档
+
+## 安装步骤
+
+### 1. 安装 Auggie CLI
+```bash
+npm install -g @augmentcode/auggie@prerelease
+```
+
+### 2. 用户认证
+```bash
+# 方式一：交互式登录
+auggie login
+
+# 方式二：使用 token（适用于 CI/CD）
+export AUGMENT_API_TOKEN="your-token"
+export AUGMENT_API_URL="https://i0.api.augmentcode.com/"
+```
+
+## Claude Code 配置
+
+### 添加到用户配置（全局）
+```bash
+claude mcp add-json auggie-mcp --scope user '{
+  "type": "stdio",
+  "command": "auggie",
+  "args": ["--mcp"],
+  "env": {
+    "AUGMENT_API_TOKEN": "your-token",
+    "AUGMENT_API_URL": "https://i0.api.augmentcode.com/"
+  }
+}'
+```
+
+### 添加到项目配置（当前项目）
+```bash
+claude mcp add-json auggie-mcp --scope project '{
+  "type": "stdio",
+  "command": "auggie",
+  "args": ["-w", "/path/to/project", "--mcp"],
+  "env": {
+    "AUGMENT_API_TOKEN": "your-token",
+    "AUGMENT_API_URL": "https://i0.api.augmentcode.com/"
+  }
+}'
+```
+
+## Codex 配置
+
+编辑 `~/.codex/config.toml`：
+```toml
+[mcp_servers."auggie-mcp"]
+command = "auggie"
+args = ["-w", "/path/to/project", "--mcp"]
+startup_timeout_ms = 20000
+```
+
+## 验证安装
+
+```bash
+# 检查 MCP 状态
+claude mcp list
+
+# 应该显示：
+# auggie-mcp: auggie --mcp - ✓ Connected
+
+# 测试功能
+claude --print "使用 codebase-retrieval 搜索当前目录下的所有文件"
+```
+
+## 工具使用示例
+
+### 1. 搜索特定文件
+```bash
+# 搜索所有 Python 文件
+claude --print "使用 codebase-retrieval 搜索 *.py 文件"
+
+# 搜索特定目录
+claude --print "使用 codebase-retrieval 搜索 src/ 目录下的文件"
+```
+
+### 2. 代码分析
+```bash
+# 分析函数实现
+claude --print "使用 codebase-retrieval 查找 main 函数的实现"
+
+# 搜索 API 端点
+claude --print "使用 codebase-retrieval 搜索所有 API 端点定义"
+```
+
+## 环境变量配置
+
+创建 `~/.augment/config` 文件：
+```json
+{
+  "apiToken": "your-token",
+  "apiUrl": "https://i0.api.augmentcode.com/",
+  "defaultModel": "gpt-4",
+  "workspaceRoot": "/path/to/project"
+}
+```
+
+## 故障排除
+
+### 1. 连接失败
+```bash
+# 检查 token
+auggie token print
+
+# 重新登录
+auggie logout && auggie login
+```
+
+### 2. 路径错误
+```bash
+# 使用绝对路径
+auggie -w $(pwd) --mcp
+
+# 检查路径是否存在
+ls -la /path/to/project
+```
+
+### 3. 权限问题
+```bash
+# 检查文件权限
+ls -la ~/.augment/
+
+# 修复权限
+chmod 600 ~/.augment/session.json
+```
+
+## 高级配置
+
+### 自定义缓存目录
+```bash
+export AUGMENT_CACHE_DIR="/custom/cache/path"
+```
+
+### 设置重试超时
+```bash
+export AUGMENT_RETRY_TIMEOUT=30
+```
+
+### 禁用确认提示
+```bash
+auggie --allow-indexing --mcp
+```
@@ -0,0 +1,49 @@
+## tmux快捷键大全（前缀 Ctrl+b）
+
+### 会话
+| 操作 | 快捷键 |
+|------|--------|
+| 脱离会话 | d |
+| 列出会话 | s |
+| 重命名会话 | $ |
+
+### 窗口
+| 操作 | 快捷键 |
+|------|--------|
+| 新建窗口 | c |
+| 关闭窗口 | & |
+| 下一个窗口 | n |
+| 上一个窗口 | p |
+| 切换到第N个窗口 | 0-9 |
+| 重命名窗口 | , |
+| 列出窗口 | w |
+
+### 窗格
+| 操作 | 快捷键 |
+|------|--------|
+| 左右分屏 | % |
+| 上下分屏 | " |
+| 切换窗格 | 方向键 |
+| 关闭窗格 | x |
+| 显示窗格编号 | q |
+| 窗格全屏/还原 | z |
+| 调整大小 | Ctrl+方向键 |
+| 交换窗格位置 | { / } |
+| 窗格转为独立窗口 | ! |
+
+### 其他
+| 操作 | 快捷键 |
+|------|--------|
+| 进入复制模式 | [ |
+| 粘贴 | ] |
+| 显示时间 | t |
+| 命令模式 | : |
+| 列出快捷键 | ? |
+
+### 命令行
+bash
+tmux                  # 新建会话
+tmux new -s 名字      # 新建命名会话
+tmux ls               # 列出会话
+tmux attach -t 名字   # 连接会话
+tmux kill-session -t 名字  # 杀掉会话
@@ -0,0 +1,59 @@
+https://x.com/3i8ae3pgjz56244/status/1993328642697707736?s=46
+
+我是把设计文档写得很细，包括service层的具体逻辑都用伪代码写了，然后交给AI，一遍直出，再用另一个AI review一遍，根据review意见修改一下，跑一下测试用例，让AI自己生成commit后push
+
+点评：需求 -> 伪代码 -> 代码
+
+---
+
+https://x.com/jesselaunz/status/1993231396035301437?s=20
+
+针对gemini 3 pro的系统prompt，使多个代理基准测试的性能提高了约 5%。
+
+---
+
+点 -> 线 -> 体 的逐级迭代，对应使用范围内的任务，先打磨好单个基础任务，然后基于此进行批量执行
+
+---
+
+https://x.com/nake13/status/1995123181057917032?s=46
+
+---
+
+https://x.com/9hills/status/1995308023578042844?s=46
+
+---
+
+文件头注释，一段话描述代码作用，上下游链路，文档维护agents或者claude维护每个模块的一段话说明，降低认知负载，尽量做减法和索引，参考claude skill
+
+---
+
+https://x.com/dogejustdoit/status/1996464777313542204?s=46
+
+随着软件规模不断扩大，靠人眼去“看代码”不仅无法应对增长的复杂度，还会让开发者疲于奔命。代码最终会被转换成机器码执行，高级语言只是一层方便人类理解的抽象，重要的是验证程序的执行逻辑，通过自动化测试、静态分析、形式化验证等手段确保行为正确。未来的软件工程核心不是“看懂代码”，而是“验证代码按正确逻辑运行”
+
+---
+
+https://x.com/yanboofficial/status/1996188311451480538?s=46
+
+```prompt
+请你根据我的要求，用 Three.js 创建一个实时交互的3D粒子系统，如果你第一次就做得好，我将会打赏你100美元的小费;我的要求是：
+```
+
+点评：这个提示词可能会提升生成的效果
+
+---
+
+https://x.com/zen_of_nemesis/status/1996591768641458368?s=46
+
+---
+
+https://github.com/tesserato/CodeWeaver
+
+CodeWeaver 将你的代码库编织成一个可导航的 Markdown 文档
+
+它能把你整个项目，不管有多少屎山代码，直接“编织”成一个条理清晰的 Markdown 文件，结构是树形的，一目了然。所有代码都给你塞进代码块里，极大地简化了代码库的共享、文档化以及与 AI/ML 工具集成
+
+---
+
+https://x.com/magic47972451/status/1998639692905087356?s=46
@@ -0,0 +1,349 @@
+# 关于手机ssh任意位置链接本地计算机，基于frp实现的方法
+
+不会弄怎么办？服务器和电脑都安装好codex（不会直接问gpt怎么安装，终端输入命令就行了），然后把文档粘贴到codex里面让他帮你配置好就行，实在不会弄，直接找我，telegram=https://t.me/desci0 x=https://x.com/123olp （ps：付费代搭）
+
+# 📌 前置准备工作（Prerequisites）
+
+在开始部署 FRP 服务端与客户端之前，请确保具备以下环境与工具。这些前置条件是保证 FRP 隧道正常工作所必需的。
+
+## 1. 基础环境要求
+
+### ✔ 一台可长期在线的 **AWS EC2 实例**
+
+* 推荐系统：Ubuntu 20.04/22.04（本文以 Ubuntu 为例）
+* 必须具备公网 IP（AWS 默认提供）
+* 需要具备修改安全组规则的权限（开放 FRP 端口）
+
+用途：作为 FRP 服务器端（frps），给 Windows 电脑提供固定访问入口。
+
+## 2. 一台能够上网的 **Windows 电脑**
+
+* Windows 10 或 Windows 11
+* 需要具备普通用户权限（但部分配置需要管理员权限）
+* 必须已安装 **OpenSSH Server**
+
+用途：作为 FRP 客户端（frpc），无论连接什么网络，都可自动挂到 AWS 上。
+
+## 3. 必需下载的软件 / 仓库
+
+### ✔ FRP（Fast Reverse Proxy）
+
+仓库地址（官方）：
+
+```
+https://github.com/fatedier/frp
+```
+
+本部署使用版本：
+
+```
+frp_0.58.1
+```
+
+下载页面：
+
+```
+https://github.com/fatedier/frp/releases
+```
+
+需要下载：
+
+* Linux 版（用于 AWS）
+* Windows 版（用于本地电脑）
+
+## 4. 必须安装的软件
+
+### ✔ Windows：OpenSSH Server + OpenSSH Client
+
+安装路径：
+
+```
+设置 → 应用 → 可选功能 → 添加功能
+```
+
+用途：提供 SSH 登录能力，让 FRP 转发到 Windows 的 SSH。
+
+## 5. 终端工具
+
+### ✔ Termius（推荐）
+
+* 用于从手机或电脑通过 SSH 连接你的 Windows
+* 支持生成 SSH Key
+* 支持管理多个主机
+
+必须使用 Termius 生成 SSH 私钥（因为你启用了“仅密钥登录”）。
+
+官方下载：
+
+```
+https://termius.com
+```
+
+## 6. 网络与端口要求
+
+在 AWS 安全组中必须开放以下端口：
+
+| 端口                             | 用途                    | 是否必须 |
+| ------------------------------ | --------------------- | ---- |
+| **FRP 控制端口**（如：1234 或 114514）  | frpc → frps 连接        | ✔ 必须 |
+| **SSH 映射端口**（如：12345 或 114515） | Termius → Windows SSH | ✔ 必须 |
+
+若使用 UFW（Ubuntu 防火墙），还需：
+
+```
+sudo ufw allow <FRP控制端口>/tcp
+sudo ufw allow <SSH映射端口>/tcp
+```
+
+## 7. 公钥 / 私钥 准备（密钥登录必需）
+
+你需要预先准备：
+
+* Termius 生成的 SSH 私钥（本地）
+* Termius 生成的 SSH 公钥（需放到 Windows 的 authorized_keys）
+
+本部署已经禁用密码登录，因此 **私钥必须妥善保管，否则将无法登录 Windows**。
+
+## 8. 基本 Linux 操作能力
+
+需要了解以下基础命令（很简单）：
+
+```
+cd /path
+nano / vim / notepad
+chmod / chown
+ps -ef | grep
+ss -lnpt
+nohup <cmd> &
+tail -f
+```
+
+你文档中都已覆盖，不会有额外要求。
+
+# 📌 前置条件总结（最终版）
+
+```
+必须具备：
+- AWS EC2（Ubuntu，带公网 IP）
+- Windows 电脑（安装 OpenSSH Server）
+- Termius（用于 SSH + 生成密钥）
+- FRP（下载 Linux + Windows 版本）
+- AWS 安全组已开放 FRP 控制端口与 SSH 映射端口
+- Termius 生成的 SSH 密钥对
+```
+
+只要满足以上前置准备，你的 FRP 隧道、SSH 密钥登录、跨网络远程访问电脑 100% 能正常运行。
+
+如果你愿意，我还可以帮你：
+
+* 把整个文档串成专业正式的一体化教程
+* 为你的文档添加「适用范围、版本说明、架构概览图、流程图」
+* 为 FRP 部署提供 systemd 服务模板
+* 为 Windows 提供后台 frpc 自启脚本（更可靠）
+
+需要的话告诉我！
+
+# FRP 服务器端部署说明
+
+本说明记录了当前 AWS EC2 (Ubuntu) 上的 FRP 服务端配置与操作方法，便于后续维护或重建。
+
+## 基本信息
+- 工作目录：`/home/ubuntu/.frp`
+- FRP 版本：`frp_0.58.1_linux_amd64`
+- 可执行文件：`/home/ubuntu/.frp/frp_0.58.1_linux_amd64/frps`
+- 配置文件：`/home/ubuntu/.frp/frp_0.58.1_linux_amd64/frps.ini`
+- 日志文件：`/home/ubuntu/.frp/frps.log`
+- 启动脚本：`/home/ubuntu/.frp/start_frps.sh`
+- 监听端口：
+  - 控制端口 `bind_port = 1234`
+  - SSH 映射端口 `12345`
+- token：`123456`
+
+## 安装步骤
+1. 新建目录并下载 FRP：
+   ```bash
+   mkdir -p /home/ubuntu/.frp
+   cd /home/ubuntu/.frp
+   wget https://github.com/fatedier/frp/releases/download/v0.58.1/frp_0.58.1_linux_amd64.tar.gz
+   tar -zxf frp_0.58.1_linux_amd64.tar.gz
+   ```
+2. 创建配置 `/home/ubuntu/.frp/frp_0.58.1_linux_amd64/frps.ini`：
+   ```ini
+   [common]
+   bind_port = 1234
+   token = 123456
+   ```
+3. 编写启动脚本 `/home/ubuntu/.frp/start_frps.sh`（已就绪）：
+   ```bash
+   #!/usr/bin/env bash
+   set -euo pipefail
+   BASE_DIR="$(cd "$(dirname "$0")" && pwd)"
+   FRP_DIR="$BASE_DIR/frp_0.58.1_linux_amd64"
+   FRPS_BIN="$FRP_DIR/frps"
+   CONFIG_FILE="$FRP_DIR/frps.ini"
+   LOG_FILE="$BASE_DIR/frps.log"
+
+   if ! [ -x "$FRPS_BIN" ]; then
+     echo "frps binary not found at $FRPS_BIN" >&2
+     exit 1
+   fi
+   if ! [ -f "$CONFIG_FILE" ]; then
+     echo "Config not found at $CONFIG_FILE" >&2
+     exit 1
+   fi
+
+   PIDS=$(pgrep -f "frps.*frps\\.ini" || true)
+   if [ -n "$PIDS" ]; then
+     echo "frps is running; restarting (pids: $PIDS)..."
+     kill $PIDS
+     sleep 1
+   fi
+
+   echo "Starting frps with $CONFIG_FILE (log: $LOG_FILE)"
+   cd "$FRP_DIR"
+   nohup "$FRPS_BIN" -c "$CONFIG_FILE" >"$LOG_FILE" 2>&1 &
+
+   sleep 1
+   PIDS=$(pgrep -f "frps.*frps\\.ini" || true)
+   if [ -n "$PIDS" ]; then
+     echo "frps started (pid: $PIDS)"
+   else
+     echo "frps failed to start; check $LOG_FILE" >&2
+     exit 1
+   fi
+   ```
+
+## 启动与停止
+- 启动/重启：
+  ```bash
+  cd /home/ubuntu/.frp
+  bash ./start_frps.sh
+  ```
+- 查看进程：`ps -ef | grep frps`
+- 查看监听：`ss -lnpt | grep 1234`
+- 查看日志：`tail -n 50 /home/ubuntu/.frp/frps.log`
+- 停止（如需手动）：`pkill -f "frps.*frps.ini"`
+
+## 安全组与防火墙
+- AWS 安全组（sg-099756caee5666062）需开放入站 TCP 1234（FRP 控制）与 12345（SSH 映射）。
+- 若使用 ufw，需执行：
+  ```bash
+  sudo ufw allow 1234/tcp
+  sudo ufw allow 12345/tcp
+  ```
+
+## 远程客户端要求
+- Windows `frpc.ini` 中 `server_addr` 指向该 EC2 公网 IP，`server_port=1234`，`remote_port=12345`，token 与服务器一致。
+- Termius/SSH 客户端使用 `ssh lenovo@<AWS IP> -p 12345`，认证方式为密钥（Termius Keychain 生成的私钥）。
+
+## 维护建议
+- FRP 官方已提示 INI 格式未来会被弃用，后续升级建议改用 TOML/YAML。
+- 可将 `start_frps.sh` 注册成 systemd 服务，确保实例重启后自动拉起。
+- 定期检查 `frps.log` 是否有异常连接或错误，并确保 token 不泄露。
+
+FRP Windows 客户端配置说明
+================================
+最后更新：2025-12-05
+适用环境：Windows 10/11，用户 lenovo，本机已安装 OpenSSH Server。
+
+一、目录与文件
+- FRP 程序目录：C:\frp\
+  - frpc.exe
+  - frpc.ini（客户端配置）
+  - start_frpc.bat（后台启动脚本）
+- SSH 密钥：
+  - 私钥：C:\Users\lenovo\.ssh\666
+  - 公钥：C:\Users\lenovo\.ssh\666.pub
+  - 管理员授权公钥：C:\ProgramData\ssh\666_keys
+
+二、frpc.ini 内容（当前生效）
+[common]
+server_addr = 13.14.223.23
+server_port = 1234
+token = 123456
+
+[ssh]
+type = tcp
+local_ip = 127.0.0.1
+local_port = 22
+remote_port = 12345
+
+三、启动与自启
+1) 手动前台验证（可选）
+   PowerShell：
+   cd C:\frp
+   .\frpc.exe -c frpc.ini
+
+2) 后台快捷启动
+   双击 C:\frp\start_frpc.bat
+
+3) 开机自启（简单方式）
+   将 start_frpc.bat 复制到启动文件夹：
+   C:\Users\lenovo\AppData\Roaming\Microsoft\Windows\Start Menu\Programs\Startup
+   下次登录自动后台启动。
+
+四、SSH 连接方式
+- 终端命令：
+  ssh -i "C:\Users\lenovo\.ssh\666" -p 12345 lenovo@13.14.223.23
+
+- Termius 填写：
+  Host 13.14.223.23
+  Port 12345
+  User lenovo
+  Key  选择 C:\Users\lenovo\.ssh\666（无口令）
+
+五、权限与安全
+- 私钥权限已限制为 lenovo、SYSTEM 可读。
+- sshd 已关闭密码登录（PasswordAuthentication no），仅密钥。
+- 管理员组用户使用 C:\ProgramData\ssh\666_keys 作为授权列表。
+
+六、常用检查
+- 查看 frpc 运行：任务管理器或
+  netstat -ano | findstr 1234
+- 查看 frpc 日志（WSL 版，如需）：/tmp/frpc-wsl.log
+- 测试 SSH：上面的 ssh 命令返回 ok 即通。
+
+七、故障排查速查
+- "Permission denied (publickey)":
+  * 确认 666 公钥在 C:\ProgramData\ssh\666_keys
+  * 确认私钥路径/权限正确。
+- "Connection refused": frps 未运行或端口 1234/12345 未放行。
+- frpc 未连接：前台运行 frpc 查看提示，或检查 frpc.ini 中 server_addr、token 是否匹配。
+
+
+Termius（手机端）连接步骤：
+
+1. 创建主机
+    - Host (Address): 13.14.223.23
+    - Port: 12345
+    - Label 可自定义（如 FRP-Home）
+2. 认证方式选择 Key
+    - 在 Authentication 选择 Key
+    - 点击 Import Key（或“从文件/粘贴”）
+    - 将本机私钥 666 的内容导入（建议用安全方式传到手机，再粘贴；如果 Termius 支持从文件导入，选该文件）。
+      私钥内容在 PC 路径：C:\Users\lenovo\.ssh\666（纯文本，-----BEGIN OPENSSH PRIVATE KEY----- 开头）。
+    - Passphrase 留空（此钥无口令）。
+3. 用户名
+    - Username: lenovo
+4. 保存并连接
+    - 首次连接接受指纹提示即可。
+5. 可选安全措施
+    - 在 Termius 中为该私钥设置本地加密密码（App 层保护）。
+    - 若不方便复制私钥，可生成移动端新钥，并将其公钥追加到 C:\ProgramData\ssh\666_keys，但目前 666 已可用，按上面导入即可。
+
+一键启动命令（在当前管理员 PowerShell 执行）
+
+# 放行、防解除阻 & 直接前台启动
+Add-MpPreference -ExclusionPath "C:\frp"
+Unblock-File C:\frp\frpc.exe
+cd C:\frp
+.\frpc.exe -c frpc.ini
+
+如果想后台启动（不占窗口）：
+
+cd C:\frp
+Start-Process -FilePath ".\frpc.exe" -ArgumentList "-c frpc.ini" -WindowStyle Hidden
+
+需要开机自启（最高权限）：
+
+schtasks /Create /TN "FRPClient" /TR "C:\frp\frpc.exe -c C:\frp\frpc.ini" /SC ONLOGON /RL HIGHEST /F /RU lenovo
@@ -0,0 +1,167 @@
+# 12Factor.me - 四阶段×十二原则方法论
+
+源：https://www.12factor.me/zh
+
+> AI 协作时代的 10x 工程效率提升方法论
+
+---
+
+## 阶段 1: 准备
+
+*建立清晰的信息架构和上下文环境*
+
+### 1. 单一真源 (Single Source of Truth)
+
+**核心概念**: 信息分散会导致上下文混乱，容易造成人机双方的误判。
+
+**推荐实践**:
+- 将所有需求、设计及上下文集中于统一的文档中心 (如 Notion / Confluence / GitHub Wiki)。
+- 与 AI 协作时，应直接引用此“真源”，而非随意复制粘贴信息。
+
+**反面模式**:
+- 团队成员各自维护不同版本的文档，导致 AI 给出的回应和建议不一致。
+
+### 2. 提示词先行 (Prompt First)
+
+**核心概念**: 将提示词 (Prompt) 视为新一代的设计文档。
+
+**推荐实践**:
+- 在任务开始前，优先编写提示词，用以明确输入、输出、风格和约束条件。
+- 团队内部复用经过验证和优化的提示词模板。
+
+**反面模式**:
+- 未经规划，直接要求 AI 编写代码，导致方向错误和不必要的返工。
+
+### 3. 上下文洁净 (Context Hygiene)
+
+**核心概念**: 干净的上下文能让 AI 更精准。
+
+**推荐实践**:
+- 每个新任务开独立会话，避免旧内容干扰
+- 定期用一句话总结现状，让 AI "对齐背景"
+
+**反面模式**:
+- 把三天前的对话和今天的任务混在一起
+
+---
+
+## 阶段 2: 执行
+
+*高效协作完成具体任务*
+
+### 4. 人类在环 (Human-in-the-Loop)
+
+**核心概念**: AI 产出快，但只有人类能把握方向与业务判断。
+
+**推荐实践**:
+- AI 给初稿，人类负责关键决策与风险把关
+- 对重要功能先进行逻辑验证，再合并代码
+
+**反面模式**:
+- 全盘接受 AI 产出，不做任何审查
+
+### 5. 任务块化 (Chunked Work)
+
+**核心概念**: 大任务拆小块，易于迭代与修正。
+
+**推荐实践**:
+- 任务控制在可 10~30 分钟完成的小范围
+- 每块结束后立即验证结果
+
+**反面模式**:
+- 一次性让 AI 写 5000 行，结果无法调试
+
+### 6. 并行流动 (Parallel Flow)
+
+**核心概念**: AI 工作时，人类做低切换成本的副任务，保持节奏不断。
+
+**推荐实践**:
+- 准备一个"副任务清单"，包含文档整理、小修复、代码审查等
+- 等待 AI 时，不接入高认知负载的新任务，避免切换开销过大
+
+**反面模式**:
+- 等待 AI 时去刷社交媒体，导致节奏断档
+
+---
+
+## 阶段 3: 协作
+
+*管理协作过程中的认知负载和工作流*
+
+### 7. 负载预算 (Cognitive Load Budget)
+
+**核心概念**: 人类注意力是稀缺资源。
+
+**推荐实践**:
+- 为 AI 协作设定每日时长上限
+- 在精神高峰期安排深度审查任务
+
+**反面模式**:
+- 全天候黏着 AI 工作，晚上完全耗尽
+
+### 8. 流保护罩 (Flow Protection)
+
+**核心概念**: 高专注流一旦被打断，恢复成本极高。
+
+**推荐实践**:
+- 设定专注时段（如 90 分钟），屏蔽通知与打扰
+- AI 交互也在专注流中批量进行，而非零散触发
+
+**反面模式**:
+- 边写代码边回微信边看 AI 输出，效率断崖式下降
+
+### 9. 可复现性 (Reproducible Sessions)
+
+**核心概念**: 协作过程可回溯，才能持续优化。
+
+**推荐实践**:
+- 保存 Prompt、AI 版本、变更原因到代码库或知识库
+- 出现 bug 时可重放生成过程
+
+**反面模式**:
+- AI 生成历史无记录，出错无法还原原因
+
+---
+
+## 阶段 4: 迭代
+
+*持续学习和改进协作模式*
+
+### 10. 休息反思 (Rest & Reflection)
+
+**核心概念**: 冲刺后复盘，才能越跑越快。
+
+**推荐实践**:
+- 冲刺结束后，花 5 分钟复盘 AI 产出与预期差异
+- 更新 Prompt 模板，积累"踩坑记录"
+
+**反面模式**:
+- 连续冲刺，累积错误不总结
+
+### 11. 技能均衡 (Skill Parity)
+
+**核心概念**: AI 是放大镜，放大能力，也放大短板。
+
+**推荐实践**:
+- 持续学习领域知识与代码审查技巧
+- 对 AI 输出保持独立判断能力
+
+**反面模式**:
+- 完全依赖 AI，失去手写能力与技术洞察力
+
+### 12. 好奇文化 (Culture of Curiosity)
+
+**核心概念**: 好奇心驱动探索，避免"盲信 AI"。
+
+**推荐实践**:
+- 面对 AI 答案，先问"为什么"，再问"还能更好吗"
+- 团队分享 AI 使用经验与改进思路
+
+**反面模式**:
+- 对 AI 方案照单全收，从不质疑
+
+---
+
+
+*生成自 [12Factor.me](https://12factor.me)*
+*许可证: MIT*
@@ -0,0 +1,194 @@
+# 🚀 Canvas白板驱动开发法
+
+## 从文字到图形：编程协作的新范式
+
+### 💡 核心发现
+
+传统开发流程：
+```
+写代码 → 口头沟通 → 脑补架构 → 代码失控 → 重构崩溃
+```
+
+**新方法**：
+```
+代码 ⇄ Canvas白板 ⇄ AI ⇄ 人类
+     ↓
+  单一事实来源
+```
+
+---
+
+### 🎯 这套方法解决了什么？
+
+**痛点1：AI看不懂你的项目结构**
+- ❌ 以前：反复解释"这个文件干什么的"
+- ✅ 现在：AI直接看白板，秒懂整体架构
+
+**痛点2：人类记不住复杂依赖**
+- ❌ 以前：改A文件忘了B依赖它，炸了
+- ✅ 现在：白板连线清晰，牵一发动全身一目了然
+
+**痛点3：团队协作靠嘴说**
+- ❌ 以前："数据流怎么走的？""呃...让我翻翻代码"
+- ✅ 现在：指着白板讲，新人5分钟看懂
+
+---
+
+### 🔥 工作流演示
+
+#### Step 1：写代码时自动更新白板
+
+```python
+# 你写了新文件 payment_service.py
+class PaymentService:
+    def process(self):
+        db.save()  # ← AI检测到数据库写入
+        stripe.charge()  # ← AI检测到外部API调用
+```
+
+**白板自动生成：**
+```
+[PaymentService] ──写入──> [数据库]
+       │
+       └──调用──> [Stripe API]
+```
+
+#### Step 2：人类和AI共同编辑白板
+
+**你在白板上拖拽**：
+- 把 `UserService` 连线到 `PaymentService`
+- AI立刻理解："哦，用户模块会调用支付"
+
+**AI读懂意图后生成代码**：
+```python
+# user_service.py
+from payment_service import PaymentService
+
+def create_order(user):
+    payment = PaymentService()
+    payment.process(user.card)  # ← AI自动加这行
+```
+
+#### Step 3：白板成为开发中枢
+
+| 操作 | 传统方式 | Canvas方式 |
+|------|----------|------------|
+| 要求AI重构 | "把支付逻辑拆出来" | 在白板拖出新节点，AI自动拆分代码 |
+| Code Review | 逐行读代码 | 看白板连线："这条调用链合理吗？" |
+| 需求变更 | 到处改代码 | 白板删条线，AI同步删除所有相关调用 |
+
+---
+
+### 🌟 关键创新点
+
+#### 1. 图形是第一公民，代码是衍生物
+
+传统思维：代码 → 文档（过期） → 架构图（更过期）
+
+新思维：**Canvas白板 = 唯一真相源**，代码只是它的序列化形式
+
+#### 2. 人类和AI的共享工作区
+
+- 人类：擅长高层设计，在白板拖拽模块
+- AI：擅长细节实现，根据白板连线生成代码
+- 协作方式：**都编辑同一个白板**，而不是来回传递文本
+
+#### 3. 实时双向同步
+
+```
+代码变化 ──自动扫描──> 更新白板
+白板编辑 ──AI解析──> 生成/修改代码
+```
+
+---
+
+### 🎨 使用场景
+
+#### 场景1：给AI派活
+
+传统：
+> "帮我写个用户注册功能，要连数据库，发邮件，记日志"
+
+Canvas方式：
+1. 在白板画3个框：`RegisterAPI` → `Database` / `EmailService` / `Logger`
+2. 告诉AI："按这个图实现"
+3. AI一次性写对所有文件和调用关系
+
+#### 场景2：Code Review
+
+传统：一行行看代码，看晕了
+
+Canvas方式：
+1. 看白板："咦，为什么前端直接连数据库？"
+2. 拖动节点调整架构
+3. AI自动重构代码
+
+#### 场景3：接手他人项目
+
+传统：看3天代码还没懂
+
+Canvas方式：
+1. 运行自动生成工具 → 1分钟得到架构白板
+2. 点开感兴趣的模块看详情
+3. 直接在白板上画出要改的部分，AI帮你定位代码位置
+
+---
+
+### 🚀 立即开始
+
+#### 工具链
+
+- **白板**：Obsidian Canvas（免费开源）
+- **自动生成**：提示词驱动（见下方）
+- **AI协作**：Claude / GPT-4（能读取Canvas JSON）
+
+#### 5分钟体验流程
+
+```bash
+# 1. 在你的项目运行自动分析
+[用提示词让AI生成架构白板]
+
+# 2. 用Obsidian打开生成的 .canvas 文件
+
+# 3. 尝试拖动模块或添加连线
+
+# 4. 把修改后的白板发给AI："按照这个新架构重构代码"
+```
+
+---
+
+### 💬 这是编程的未来吗？
+
+我认为是的，原因：
+
+1. **图形语言是人类大脑的母语**
+   - 你能瞬间理解地铁线路图
+   - 但看不懂等效的换乘文字说明
+
+2. **AI已经足够聪明去"看懂"图**
+   - Canvas就是结构化的图形数据
+   - AI解析JSON比解析你的自然语言描述准确10倍
+
+3. **代码生成已经商品化，架构设计才是稀缺能力**
+   - 未来程序员的工作：设计白板架构
+   - AI的工作：把白板翻译成代码
+
+---
+
+### 📌 金句总结
+
+> "当代码变成白板上的方块，编程就从打字变成了搭积木。"
+
+> "最好的文档不是Markdown，是能直接驱动AI工作的架构图。"
+
+> "AI看懂你的图，比看懂你的话，容易一万倍。"
+
+---
+
+### 🔗 相关资源
+
+- [Canvas白板生成提示词](https://docs.google.com/spreadsheets/d/1Ifk_dLF25ULSxcfGem1hXzJsi7_RBUNAki8SBCuvkJA/edit?gid=1777853069#gid=1777853069&range=A1) - 自动生成架构白板的完整提示词
+- [白板驱动开发系统提示词（在线提示词库入口）](../../prompts/README.md) - 系统提示词已迁移到云端表格
+- [Obsidian Canvas 官方文档](https://obsidian.md/canvas)
+- [胶水编程](../00-基础指南/胶水编程.md) - 能抄不写，能连不造
+- [通用项目架构模板](../00-基础指南/通用项目架构模板.md) - 标准化目录结构