yourdomain.com SSL 证书自动化方案

为 yourdomain.com 域名签发 Let's Encrypt 通配符证书，通过腾讯云 SCF 云函数自动续签，本地 Tengine 部署，证书存 COS 备份并上传到 SSL 证书管理。

目录

1. 架构概览
2. ACME 协议与 Let's Encrypt
3. 项目结构
4. 核心流程详解
5. DNS-01 挑战
6. SCF 云函数自动部署
7. 本地 Tengine 部署
8. 证书上传到腾讯云 SSL 管理
9. 运行日志示例
10. 维护命令

1. 架构概览

┌─────────────────────────────────────────────────────────────┐
│                    用户请求 HTTPS                            │
│                         │                                    │
│                   ┌─────┴──────┐                            │
│                   │  Tengine   │  本地 Web 服务器             │
│                   │  :80 → 301 │                            │
│                   │  :443 SSL  │                            │
│                   └─────┬──────┘                            │
│                         │ 读取证书                            │
│                   ┌─────┴──────┐   /usr/local/tengine/certs/ │
│                   │  COS 存储   │   fullchain.pem              │
│                   │  (广州)     │   privkey.pem                │
│                   └─────┬──────┘                            │
│                         │                                    │
│          ┌──────────────┼──────────────┐                     │
│          │              │              │                     │
│   ┌──────┴──────┐ ┌────┴─────┐ ┌─────┴──────┐              │
│   │ SCF 云函数  │ │ SSL 证书  │ │ 本地备份   │              │
│   │ 自动续签    │ │ 管理平台  │ │ scf-ssl/   │              │
│   │ ap-shanghai │ │ CERTIFICATE_ID │ │ certs/     │              │
│   └──────┬──────┘ └──────────┘ └────────────┘              │
│          │                                                  │
│   ┌──────┴──────┐                                          │
│   │  Let's      │  ACME v2 协议                             │
│   │  Encrypt    │  DNS-01 挑战                              │
│   │  CA         │◄────────────────────────────              │
│   └─────────────┘                                          │
│          │                                                  │
│   ┌──────┴──────┐                                          │
│   │  DNSPod     │  TXT 记录 _acme-challenge                 │
│   │  域名解析    │  添加/删除                                │
│   └─────────────┘                                          │
└─────────────────────────────────────────────────────────────┘

2. ACME 协议与 Let's Encrypt

ACME（Automatic Certificate Management Environment）

ACME v2 是 IETF 标准协议（RFC 8555），用于自动化证书申请和管理。Let's Encrypt 是全球最大的 ACME CA。

核心概念：

挑战类型

本方案选择 DNS-01，原因：

• 支持通配符证书 *.yourdomain.com
• 不需要对外暴露 HTTP 服务
• 通过 DNSPod API 自动完成

3. 项目结构

scf-ssl/
├── src/
│   ├── index.js        SCF 主入口 + 流程编排
│   ├── config.js       环境变量配置模块
│   ├── acme.js         ACME 协议核心逻辑
│   ├── dnspod.js       DNSPod API（TC3-HMAC-SHA256）
│   └── cos-store.js    COS 对象存储读写
├── deploy.js           SCF 一键部署脚本
├── certs/              本地证书文件（gitignore）
├── package.json
├── .env.example
└── README.md

4. 核心流程详解

4.1 完整签发流程

SCF 触发 → 从 COS 读取 meta.json
  │
  ├─ 到期 > 15 天
  │   └─ 跳过，直接返回
  │
  └─ 需要续签（或首次）
      │
      ├─ 1. 加载 ACME 账户密钥
      │     ├─ COS 有 account-key.pem → 直接使用
      │     └─ 首次运行 → 生成 RSA 4096 密钥 → 保存到 COS
      │
      ├─ 2. 连接 Let's Encrypt
      │     ├─ ENV=staging → acme-staging-v02.api.letsencrypt.org ✓ 无速率限制
      │     └─ 生产环境  → acme-v02.api.letsencrypt.org ⚠️ 有速率限制
      │
      ├─ 3. 注册账户（首次自动创建）
      │     POST /acme/new-account
      │     { termsOfServiceAgreed: true, contact: ["mailto:email"] }
      │
      ├─ 4. 生成 CSR
      │     域名私钥 (RSA 2048)
      │     ├─ CN = yourdomain.com
      │     └─ SAN = [yourdomain.com, *.yourdomain.com]
      │
      ├─ 5. 下单
      │     POST /acme/new-order
      │     identifiers: [
      │       { type: "dns", value: "yourdomain.com" },
      │       { type: "dns", value: "*.yourdomain.com" }
      │     ]
      │
      ├─ 6. 获取鉴权 + DNS-01 挑战
      │     每个 identifier 一个 authorization
      │     每个 authorization 包含 dns-01 challenge
      │
      ├─ 7. DNS 挑战（以下在 auto 模式中自动完成）
      │     ├─ challengeCreateFn  →  DNSPod 添加 TXT 记录
      │     ├─ 等待 60 秒 DNS 传播
      │     ├─ verifiyChallenge  →  本地验证 DNS 已生效
      │     ├─ completeChallenge  →  通知 Let's Encrypt 验证
      │     └─ challengeRemoveFn →  DNSPod 删除 TXT 记录
      │
      ├─ 8. Finalize 订单
      │     POST /acme/order/{id}/finalize
      │     { csr: "base64 CSR" }
      │
      ├─ 9. 下载证书
      │     GET /acme/cert/{id}
      │     → 返回 PEM 格式证书链（3 张证书）
      │
      └─ 10. 保存到 COS
            ├─ fullchain.pem    证书链
            ├─ privkey.pem      域名私钥
            └─ meta.json        到期元信息

4.2 SCF 主入口 (src/index.js)

export async function main_handler(event, context) {
  // 1. 读取 COS meta.json，检查到期时间
  const meta = await cosStore.readMeta(config.domain)

  if (meta && daysUntilExpiry(meta.expiresAt) > 15) {
    return { status: "skipped", daysRemaining }  // 无需续签
  }

  // 2. 加载 ACME 账户密钥
  const accountKey = await loadOrCreateAccountKey(config.domain)

  // 3. 完整 ACME 签发流程
  const result = await requestCertificate(config.domain, accountKey)

  // 4. 保存证书到 COS
  await cosStore.saveCertificates(config.domain, result)
  await cosStore.writeMeta(config.domain, result)
}

4.3 使用 acme-client 的 auto 模式

本项目使用 acme-client npm 包的 auto 模式，它封装了整个 ACME 流程：

const certificate = await client.auto({
  csr: csrBuf,
  email: config.email,
  termsOfServiceAgreed: true,
  challengePriority: ["dns-01"],

  // 挑战前：添加 DNS TXT 记录
  challengeCreateFn: async (authz, challenge, keyAuthorization) => {
    const value = keyAuthorization  // 这是 DNS-01 的 TXT 记录值
    await dnspod.addTxtRecord(domain, "_acme-challenge", value)
    await sleep(60000)  // 等待 DNS 传播
  },

  // 挑战后：清理 DNS TXT 记录
  challengeRemoveFn: async () => {
    await dnspod.cleanChallengeRecords(domain, "_acme-challenge")
  },
})

5. DNS-01 挑战

5.1 DNSPod API 调用（TC3-HMAC-SHA256 签名）

腾讯云 API 使用 TC3-HMAC-SHA256 签名算法。核心步骤：

function sign(secretId, secretKey, action, params) {
  const algorithm = "TC3-HMAC-SHA256"
  const timestamp = Math.floor(Date.now() / 1000)
  const date = new Date(timestamp * 1000).toISOString().slice(0, 10)
  const service = "dnspod"
  const endpoint = "dnspod.tencentcloudapi.com"

  // Step 1: 构建 CanonicalRequest
  const payload = JSON.stringify(params)
  const hashedPayload = sha256(payload)
  const canonicalRequest = [
    "POST",
    "/",
    "",
    `content-type:application/json
host:${endpoint}
`,
    "content-type;host",
    hashedPayload,
  ].join("
")

  // Step 2: 构建 StringToSign
  const stringToSign = [
    algorithm,
    timestamp,
    `${date}/${service}/tc3_request`,
    sha256(canonicalRequest),
  ].join("
")

  // Step 3: 派生签名密钥
  const kDate = hmacSha256("TC3" + secretKey, date)
  const kService = hmacSha256(kDate, service)
  const kSigning = hmacSha256(kService, "tc3_request")
  const signature = hmacSha256(kSigning, stringToSign)

  // Step 4: 构建 Authorization
  const authorization = `${algorithm} Credential=${secretId}/${date}/${service}/tc3_request, SignedHeaders=content-type;host, Signature=${signature}`

  return { authorization, timestamp, payload }
}

5.2 通配符证书的特殊处理

通配符证书需要同时验证两个 identifier：

注意： 两个 identifier 使用相同的主机记录但不同的值！

在 challengeCreateFn 中不能先清理再添加，否则会导致两条记录互相覆盖。 正确的做法是直接追加 TXT 记录（DNSPod 支持相同主机记录的多条 TXT）， 在 challengeRemoveFn 中统一清理。

// ✅ 正确做法
challengeCreateFn: async (authz, challenge, keyAuthorization) => {
  // 不清理，直接添加（两条不同的 TXT 记录共存）
  await dnspod.addTxtRecord(domain, "_acme-challenge", keyAuthorization)
  await sleep(60000)
}

// ❌ 错误做法（会导致通配符记录被覆盖）
challengeCreateFn: async (authz, challenge, keyAuthorization) => {
  await dnspod.cleanChallengeRecords(domain, "_acme-challenge")  // 不要!
  await dnspod.addTxtRecord(domain, "_acme-challenge", keyAuthorization)
}

6. SCF 云函数自动部署

6.1 部署脚本 (deploy.js)

async function main() {
  // 1. 打包代码（ZipArchive）
  const archive = new ZipArchive({ zlib: { level: 9 } })
  archive.file("src/index.js", { name: "index.js" })
  archive.file("src/config.js", { name: "config.js" })
  archive.file("src/acme.js", { name: "acme.js" })
  archive.file("src/dnspod.js", { name: "dnspod.js" })
  archive.file("src/cos-store.js", { name: "cos-store.js" })
  archive.directory("node_modules/", "node_modules/")
  // 注意: SCF 要求入口文件在 zip 根目录

  // 2. 上传到 COS

  // 3. 调用 CreateFunction API
  await callAPI("scf", "CreateFunction", {
    FunctionName: "ssl-auto-renew",
    Runtime: "Nodejs18.15",
    Handler: "index.main_handler",
    Code: { CosBucketName, CosBucketRegion, CosObjectName },
    Timeout: 180,
    MemorySize: 128,
    Environment: { Variables: [...] },
  })

  // 4. 创建定时触发器
  await callAPI("scf", "CreateTrigger", {
    Type: "timer",
    TriggerDesc: "0 3 1,16 * *",  // 每月 1日、16日 03:00
    Enable: "OPEN",
  })
}

6.2 部署命令

SECRET_ID=xxx SECRET_KEY=xxx COS_BUCKET=xxx node deploy.js

6.3 SCF 函数配置

6.4 环境变量

7. 本地 Tengine 部署

7.1 编译安装 Tengine

# 安装编译依赖
sudo apt-get install -y libpcre3-dev libssl-dev zlib1g-dev build-essential

# 下载 Tengine 3.1.0
wget https://tengine.taobao.org/download/tengine-3.1.0.tar.gz
tar xzf tengine-3.1.0.tar.gz
cd tengine-3.1.0

# 编译配置
./configure \
  --prefix=/usr/local/tengine \
  --sbin-path=/usr/local/tengine/sbin/nginx \
  --conf-path=/usr/local/tengine/conf/nginx.conf \
  --with-http_ssl_module \
  --with-http_v2_module \
  --with-stream \
  --with-stream_ssl_module

# 编译安装
make -j$(nproc)
sudo make install

7.2 Nginx 配置

server {
    listen 80;
    server_name yourdomain.com www.yourdomain.com;
    return 301 https://yourdomain.com$request_uri;
}

server {
    listen 443 ssl http2;
    server_name yourdomain.com;

    ssl_certificate     /usr/local/tengine/certs/fullchain.pem;
    ssl_certificate_key /usr/local/tengine/certs/privkey.pem;

    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
    ssl_prefer_server_ciphers on;
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 10m;

    root /var/www/yourdomain.com;
    index index.html;
}

7.3 加载证书

sudo cp certs/fullchain.pem /usr/local/tengine/certs/
sudo cp certs/privkey.pem /usr/local/tengine/certs/
sudo /usr/local/tengine/sbin/nginx -t     # 验证配置
sudo /usr/local/tengine/sbin/nginx        # 启动
sudo /usr/local/tengine/sbin/nginx -s reload  # 重载

8. 证书上传到腾讯云 SSL 管理

通过 ssl.tencentcloudapi.com 的 UploadCertificate API：

const result = await callAPI("ssl", "UploadCertificate", {
  CertificatePublicKey: fullchainPem,
  CertificatePrivateKey: privkeyPem,
  Alias: "yourdomain.com (*.yourdomain.com)",
  ProjectId: 0,
})
// 返回 CertificateId: "CERTIFICATE_ID"

上传后可在腾讯云控制台 → SSL 证书管理 中查看，可用于 CDN、CLB、API 网关等服务。

9. 运行日志示例

首次签发

[ssl-auto-renew] 开始执行
[ssl-auto-renew] 环境模式: production(正式)
[ssl-auto-renew] 目标域名: yourdomain.com
[ssl-auto-renew] 检查现存证书...
[ssl-auto-renew] 未找到现存证书，首次签发
[ssl-auto-renew] 准备 ACME 账户密钥...
[ACME] 生成新账户密钥 (RSA 4096)
[COS] ACME 账户密钥已保存
[ssl-auto-renew] 开始 ACME 签发流程...
[ACME] 目标 CA: PRODUCTION (正式)
[ACME] 为 yourdomain.com 签发证书
[ACME] 生成域名密钥对和 CSR（含通配符 *.yourdomain.com）
[ACME] 启动 auto 模式...
[ACME] DNS-01 挑战: yourdomain.com → SOMVYBzEItFCNctq1PYV...
[DNSPod] 添加 TXT 记录: _acme-challenge.yourdomain.com
[ACME] 等待 DNS 传播 (60s)...
[DNSPod] 挑战记录已清理
[ACME] ✅ 证书签发成功!
[ACME]    签发日期: 2026-07-14T02:26:31Z
[ACME]    到期日期: 2026-10-12T02:26:31Z
[COS] 证书已保存: fullchain.pem + privkey.pem
[ssl-auto-renew] ✅ 签发成功!  耗时: 220.8s

跳过续签

[ssl-auto-renew] 开始执行
[ssl-auto-renew] 检查现存证书...
[ssl-auto-renew] 现存证书到期日: 2026-10-12, 剩余 89 天
[ssl-auto-renew] 证书仍有效 (89 天 > 15 天)，无需续签，跳过

证书验证

# 检查 SAN（Subject Alternative Name）
openssl x509 -in fullchain.pem -noout -ext subjectAltName
# → DNS:*.yourdomain.com, DNS:yourdomain.com

# 检查有效期
openssl x509 -in fullchain.pem -noout -dates
# → notBefore=Jul 14 01:27:59 2026 GMT
# → notAfter=Oct 12 01:27:58 2026 GMT

# 检查 TLS 握手
openssl s_client -connect localhost:443 -servername yourdomain.com

10. 维护命令

证书相关

# 从 COS 下载证书
node -e "
  import COS from 'cos-nodejs-sdk-v5';
  const cos = new COS({ SecretId, SecretKey });
  cos.getObject({ Bucket, Key: 'ssl/yourdomain.com/fullchain.pem' }, ...);
"

# 更新 Tengine 证书
sudo cp fullchain.pem /usr/local/tengine/certs/
sudo cp privkey.pem /usr/local/tengine/certs/
sudo /usr/local/tengine/sbin/nginx -s reload

# 上传到腾讯云 SSL 管理
node deploy-ssl-manager.js

SCF 相关

# 部署
SECRET_ID=xxx SECRET_KEY=xxx COS_BUCKET=xxx node deploy.js

# 本地测试（staging）
cd scf-ssl && ENV=staging node src/index.js

# 本地测试（production）
cd scf-ssl && node src/index.js

证书到期管理

附录 A：使用的服务

附录 B：依赖的 npm 包

附录 C：关键文件路径

🧰 Nacos Skills 完整速查手册

你的 Claude Code 上一共安装了 192 个 Skills，按场景分类整理如下。

怎么用这本手册：

• 想做什么事 → 找到对应的分类 → 看看哪个 skill 名最匹配
• 直接用那句话跟我说就行，我会自动调用对应的 Skill
• 以下 "触发方式" 列出的关键词就是你直接说出来的话

📖 目录

1. 开发工作流（最常用）
2. 代码审查 & 质量
3. Bug 调试 & 维护
4. 计划 & 设计
5. 文档 & 写作
6. 文件生成（docx/xlsx/pptx/pdf）
7. AI 图片生成
8. AI 视频生成
9. AI 音频 & 语音
10. AI 内容创作（综合）
11. Cloudflare 全家桶
12. 前端 & UI 设计
13. 微信小程序
14. 营销 & 增长
15. 广告 & 创意
16. SEO & 搜索
17. 数据 & 分析
18. 设计 & 品牌
19. Skill 管理
20. 工具 & 其他

1. 开发工作流（最常用）

2. 代码审查 & 质量

3. Bug 调试 & 维护

4. 计划 & 设计

5. 文档 & 写作

6. 文件生成

7. AI 图片生成

能调用的 AI 模型：FLUX、Gemini、Grok、Seedream、Reve、Imagen、Qwen 等 50+ 模型

8. AI 视频生成

能调用的模型：Google Veo、Seedance、Wan、Grok Video、HunyuanVideo 等 40+ 模型

9. AI 音频 & 语音

能调用的模型：ElevenLabs、Kokoro TTS、DIA、Chatterbox、Higgs 等

10. AI 内容创作（综合）

11. Cloudflare 全家桶

12. 前端 & UI 设计

UI 微调 & 优化

13. 微信小程序

14. 营销 & 增长

15. 广告 & 创意

16. SEO & 搜索

17. 数据 & 分析

18. 设计 & 品牌

19. Skill 管理

20. 工具 & 其他

💡 快速索引

我日常写代码时最可能用到的 Top 20

writing-plans        → 写计划
brainstorming        → 讨论方案
systematic-debugging → 排查 Bug
code-review          → 审查代码
requesting-code-review → 提交前审查
simplify             → 代码简化
verification-before-completion → 交付前确认
karpathy-guidelines  → 编码规范
doc-coauthoring      → 写文档
py-refactor          → Python 重构
test-driven-development → TDD
subagent-driven-development → 并行开发
finishing-a-development-branch → 收尾分支
internal-comms       → 写周报
frontend-design      → 前端设计
ui-ux-pro-max        → UI 设计
skill-creator        → 创建 Skill
writing-skills       → 写 Skill 描述
mcp-builder          → 构建 MCP Server
using-git-worktrees  → Git 隔离开发

关键词 → Skill 快速查找

💡 记住一句话就够了：不用记！

直接跟我说你想做什么，我会自动匹配最合适的 Skill。 这本手册是给你浏览参考用的，不是让你背诵的 😊%

Claude Code 高效用法 — 完整手册

解决一个核心问题：如何减少"一问一答"的低效循环，让 Agent 一次做对事。

一、为什么聊天效率低

默认行为的问题

你：帮我修这个 Bug
        ↓
Agent 扫一眼代码 → *猜*一个原因 → 直接改
        ↓
     改错了
        ↓
你：不对，是 xxx 的原因
        ↓
Agent 又 *猜*一个 → 又改
        ↓
     还是不对
        ↓
... 来回 3-5 轮

根因：Agent 没有花那 30 秒先彻底搞懂问题就动手了。 "猜 → 改 → 错 → 再猜" 的循环。

解决方案：先出计划，再执行

你：帮我修这个 Bug
        ↓
Agent 先输出一个排查计划（用 systematic-debugging skill）
        ↓
你扫一眼计划 → "方向不对，先检查日志"
        ↓
Agent 修正计划
        ↓
你确认 → Agent 按计划执行 → 一次到位

从"改代码 3-5 次"变成"改计划 1 次 + 执行 1 次"。 计划是文本，改起来 5 秒；代码改错了要回滚重来。

二、强制规则：写在 CLAUDE.md 里

在项目根目录 CLAUDE.md 写入：

## 效率规则（强制）

遇到以下情况，**必须先输出计划/方案，确认后再执行**：

1. **修 Bug** → 先用 `systematic-debugging` 输出排查步骤
   - 定位根因 → 确认 → 修复
2. **加功能** → 先用 `writing-plans` 输出实现方案
   - 方案 A / 方案 B / 方案 C → 确认用哪个 → 实现
3. **重构** → 先用 `brainstorming` 或 `writing-plans` 输出方案
   - 涉及哪些文件、不改哪些、分几步、怎么验证
4. **复杂变更** → 用 `writing-plans` + `executing-plans`

未经确认就动手改代码 → 驳回。

实际对话效果

加上这条规则后：

你：战斗系统退出战斗时有 Bug
    ↓
Agent：好的，让我用 systematic-debugging 排查。

排查计划：
1. 检查 B_SEND(fid=14) 发送的结束战斗指令格式
2. 检查服务端 BU 消息的处理
3. 检查客户端 Battle 状态机是否在等待超时

你看这个方向对吗？
    ↓
你：先查第 3 项，我怀疑是状态机没重置
    ↓
Agent：好，直接检查 Battle.ts → 找到问题 → 一次修好

总对话轮数：3 轮（确认计划 1 轮 + 确认修正 1 轮 + 执行结果 1 轮） 没有规则时：5-8 轮（猜→改→错→再猜→再改...）

三、并行工作：run_in_background

什么时候用

怎么用

不需要记任何语法，说人话就行：

帮我在后台检查一下 Nacos 上的接口契约和 server/mock.js 有没有对齐
查完了告诉我

Claude 会自己决定要不要在后台跑。

内部原理（不用记，了解即可）

Claude Code 会调用 Agent 工具，设置 run_in_background: true，启动一个独立的子会话。子会话有自己的上下文窗口，不占用你当前会话的 token。做完后通知你。

进阶：Worktree 隔离

如果后台任务也要改代码，用 worktree 隔离，互不干扰：

在后台帮我做一个独立的分支实现登录接口，跟我当前改的代码不冲突

四、后台持续监听：Monitor

不是所有场景都要后台 Agent 跑一遍就结束。有些场景需要持续监控：

# 场景：正在构建项目，你想知道什么时候完成
Monitor(
  command="npm run build 2>&1 | tail -f",
  description="等待构建完成"
)

五、Task 跟踪列表

Claude Code 内置了任务列表功能，让你看到当前在做什么：

TaskCreate("修复登录 Bug")         # 创建一个任务
TaskList()                         # 查看所有任务
TaskUpdate(taskId, status="done")  # 标记完成
TaskStop(taskId)                   # 终止任务

和 Kanban/Nacos 的关系

如果你需要：                        用：
────────────────────────────────────────────────
当前会话内跟踪进度 → TaskCreate
跨会话任务跟踪     → Hermes Kanban / Nacos 配置
跨机器任务协调     → Nacos 通知（sa-notify）

六、CLAUDE.md 最佳实践

必须包含的内容

## 📋 项目信息
- 技术栈、构建工具、目录结构

## 🎯 开发工作流
- 每次任务自动执行：改代码 → 跑测试 → lint → 提交

## 🧰 Skills 映射表
- 什么场景用什么 skill（方便 Agent 匹配）

## 📝 行为约定
- 每次开始先说用了什么 skills
- 修改前先读
- 不随意删除

## ⚡ 效率规则
- 先计划再执行（上面写的强制规则）

## ✅ 检查清单
- 测试通过了？lint 过了？提交了？

跨 Agent 共享

你机器上有 10 个 Agent。想让所有 Agent 读同一套规则：

# Claude Code 读 CLAUDE.md
# Codex 读 AGENTS.md
# Cline 读 .clinerules

# 全部指向同一个文件
ln -sf CLAUDE.md AGENTS.md       # Codex 用

已经通过 nacos-cli skill-sync 做好了的配置：

• Claude Code: 191 skills
• Codex: 191 skills（含 AGENTS.md symlink）
• Cursor / OpenClaw / Hermes / 其他: 同步完成

Hermes Orchestrator（编排器）— 完整手册

Orchestrator 是 Hermes 的"大脑"，收到复杂任务时自动判断要不要拆解、怎么拆、派发给谁。

一、为什么需要 Orchestrator

没有 Orchestrator 时，Agent 只有一个会话、一条线：

你：帮我把登录系统做完
     ↓
Agent：好的
     → 先写界面（30s）
     → 再写网络层（30s）
     → 再写服务端（60s）
     总共耗时：120s 串行
     ↓
你：干等着它一个个做

有 Orchestrator 时：

你：帮我把登录系统做完
     ↓
Orchestrator：
  "这个任务可以拆成 3 个互不依赖的子任务"
     ↓
  并发派发：
    Worker A → 写界面     (30s)
    Worker B → 写网络层    (30s)    ← 同时进行
    Worker C → 写服务端    (60s)
    总共耗时：60s（最慢的那个）
     ↓
  收集结果 → 汇报

时间节省：120s → 60s，而且你不用参与中间过程。

二、Orchestrator 的判断逻辑

收到一个任务时，Orchestrator 的工作流程：

收到任务
    ↓
是否开启编排？（orchestrator_enabled）
    ├── 否 → 当作普通任务，自己不拆，单线程做
    └── 是 → 判断能否分解
            ↓
    有 auto_decompose？
    ├── 否 → 等待你用 writing-plans 告诉它怎么拆
    └── 是 → 自动分析任务，决定：
            │
            ├── 太简单（改个变量名）→ 不拆，自己直接做
            ├── 中等（改一个模块）→ 拆 2-3 个子任务
            └── 复杂（重构整个项目）→ 拆多个子任务 + 分批派发
                 ↓
    派发给 worker（最多 max_concurrent_children 个）

三、配置详解

# ~/.hermes/config.yaml
delegation:
  orchestrator_enabled: true       # 是否启用编排
                                   # true → 自动拆解大任务
                                   # false → 所有任务单线程做

  max_concurrent_children: 3       # 同时最多几个子任务并行
                                   # 设置太大：API 并发超限
                                   # 设置太小：串行效率低
                                   # 3 是平衡值

  max_async_children: 3            # 后台异步子任务上限
                                   # 和上面的区别：
                                   # concurrent = 你还在对话中
                                   # async = 你切去做别的事了

  max_spawn_depth: 1               # 子任务能不能再拆孙子任务
                                   # 0 = 不拆
                                   # 1 = 子任务不能再拆
                                   # 2 = 子任务可以拆孙子任务
                                   # 防止无限递归

  child_timeout_seconds: 0         # 子任务超时时间
                                   # 0 = 不限时
                                   # 3600 = 1 小时没做完强制终止

  subagent_auto_approve: false     # 子任务操作是否自动批准
                                   # false → 每个子任务操作需要你确认
                                   # true → 子任务自己决定，不打扰你

  max_iterations: 50               # 单个任务的总体迭代次数上限
                                   # 防止死循环

  orphan_timeout: 300              # 子任务失联后多久判定为孤儿（秒）
                                   # 仅 gateway 模式有效

和 Claude Code 的对比

四、实际使用方式

方式 1：完全自动（推荐）

什么都不用配置，直接说：

重构战斗系统的核心逻辑，包括状态机、AI、伤害计算

Hermes 自动判断能不能拆、怎么拆、并发跑。

方式 2：指定 worker profiles

如果有多台机器的 Hermes 实例：

# ~/.hermes/profiles/client.yaml → 客户端开发机器
# ~/.hermes/profiles/server.yaml → 服务端开发机器

帮我把登录系统做了，客户端部分用 client profile，服务端部分用 server profile

方式 3：和 Kanban Swarm 配合

hermes kanban swarm "实现登录系统" \
  --worker client:登录界面 \
  --worker server:登录接口 \
  --verifier senior-dev \
  --synthesizer lead-dev

Kanban 上会看到 5 张卡片（3 Worker + 1 Verifier + 1 Synthesizer），Orchestrator 控制执行顺序。

五、常见问题

Q: Orchestrator 能编排 Claude Code 吗？

不能。Orchestrator 只能在 Hermes 自己的 profiles 之间编排。如果需要编排 Claude Code，需要通过 Nacos 或共享看板的方式间接协作。

Q: 自动拆错了怎么办？

auto_decompose: true 不一定每次拆得对。可以显式关闭自动拆解：

auto_decompose: false

然后你自己用 writing-plans 输出方案让 Hermes 执行。

Q: 子任务做一半失败了？

failure_limit=2：同一任务重试 2 次还是失败，就标记 Failed 并通知你。你修复后手动 promote 重新执行。

Q: 3 个并发不够？

max_concurrent_children: 5

但注意 API 并发限制，一般 3 是安全值。

六、Orchestrator 执行过程（有 Kanban 时）

Orchestrator 检测到看板上有新任务
    ↓
Kanban: Todo → In Progress（标记为有人在做）
    ↓
子任务拆分
    ↓
每个子任务创建为独立卡片，建立依赖关系
    ↓
子任务 Ready → worker claim → 执行
    ↓
worker 完成 → Kanban: Done
    ↓
依赖该子任务的其他子任务自动变为 Ready
    ↓
所有子任务 Done
    ↓
父任务 Done

Hermes 多平台同源 — 完整手册

同一个 Hermes 实例，同时在 CLI、Telegram、Discord、Slack 等多个平台上工作。所有平台共享同一份会话和记忆。

一、核心概念

什么是"同源"

不是"多设备登录同一个账号"，而是：

你在 CLI 里：帮我把登录功能做了
                      ↓
Hermes 开始干活，会话进入"任务进行中"
                      ↓
你合上电脑，出门在地铁上打开 Telegram：
  给 Hermes bot 发：那个登录功能做完了吗？
                      ↓
Hermes 知道你在说哪个任务：
  "还在做，Worker B 在处理网络层，预计 5 分钟"

CLI 和 Telegram 看到的是同一个 Hermes、同一个会话、同一个状态。

架构

┌────────────────────────────────────────────────┐
│              Hermes Gateway                      │
│                                                  │
│   ┌────────┐  ┌──────────┐  ┌──────┐  ┌──────┐ │
│   │  CLI   │  │ Telegram │  │Discord│  │Slack │ │
│   └────┬───┘  └────┬─────┘  └──┬───┘  └──┬───┘ │
│        │           │           │         │      │
│   ┌────┴───────────┴───────────┴─────────┴────┐ │
│   │         统一路由层 + 会话管理               │ │
│   └────────────────┬──────────────────────────┘ │
│                    │                            │
│   ┌────────────────┴──────────────────────────┐ │
│   │      共享记忆 + 共享 Skills + 共享看板      │ │
│   └───────────────────────────────────────────┘ │
└──────────────────────────────────────────────────┘

二、配置步骤

第一步：安装 Gateway 依赖

Gateway 需要长期运行的后台服务。

# 安装为系统服务（macOS launchd / Linux systemd）
hermes gateway install

第二步：交互式配置

hermes gateway setup

这是一个向导，会依次问你：

? 是否启用 Telegram？(y/N)
? 输入 Telegram Bot Token：123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
? 是否启用 Discord？(y/N)
? 输入 Discord Bot Token：...
? 是否启用 Slack？(y/N)
...

配置完成后写入 ~/.hermes/config.yaml。

第三步：启动 Gateway

# 后台服务（推荐）
hermes gateway start
hermes gateway status      # 确认运行中

# 或前台运行（看实时日志）
hermes gateway run

# 停止
hermes gateway stop

三、各平台详细配置

Telegram

步骤：

1. 打开 Telegram，搜索 @BotFather
2. 发送 /newbot，按提示创建 bot，取名
3. BotFather 给你一个 token：123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
4. hermes gateway setup → 选 Telegram → 填入 token
5. 在 Telegram 里找到你的 bot，点 Start

配置项：

telegram:
  require_mention: false        # 群聊里要不要 @bot 才回复
  free_response_channels: ''     # 哪些频道不用 @ 也能触发
  allowed_chats: ''              # 只允许这些聊天使用（空=全部）
  reactions: false               # 给消息加 emoji 反应
  channel_prompts: {}            # 不同频道设置不同的 prompt
  extra:
    rich_messages: false         # 是否支持富文本（按钮、卡片等）

Discord

1. 去 https://discord.com/developers/applications 创建应用
2. 创建 Bot，复制 token
3. 在 OAuth2 → URL Generator 勾选 bot → 生成邀请链接
4. 把 bot 邀请到你的服务器
5. hermes gateway setup → 选 Discord → 填入 token

配置项：

discord:
  require_mention: true          # 需要 @Hermes 才回复
  auto_thread: true              # 自动建线程（避免刷屏）
  thread_require_mention: false  # 线程里也要 @ 才回复
  history_backfill: true         # 恢复会话时拉取最近消息
  history_backfill_limit: 50     # 拉取最近 50 条
  reactions: true                # 给消息加 emoji
  dm_role_auth_guild: ''         # 仅某个角色的用户能 DM bot
  allowed_channels: ''           # 只在这些频道工作（空=全部）
  server_actions: ''             # 是否允许 bot 管理服务器
  channel_prompts: {}            # 不同频道不同 prompt

Slack

# 先生成 manifest 文件
hermes slack manifest
# 输出一个 JSON，到 Slack API 后台创建 app 时用

配置项：

slack:
  require_mention: true
  free_response_channels: ''     # 这些频道不用 @ 也能触发
  allowed_channels: ''           # 只在这些频道工作
  channel_prompts: {}

WhatsApp

hermes whatsapp                 # WhatsApp 个人号集成
hermes whatsapp-cloud           # WhatsApp Business API

四、跨平台使用技巧

1. CLI 和手机交替工作

在 CLI 里发起任务：
  $ hermes chat
  > 重构战斗系统状态机

出门后继续：
  打开 Telegram → 给 bot 发消息
  "做完了吗？"
  → Hermes 回复进度
  "把伤害计算公式改成百分比"
  → Hermes 更新任务规格

回到电脑前：
  CLI 里继续上下文
  $ hermes chat
  # 自动恢复上次会话

2. 不同平台设不同角色

channel_prompts:
  telegram:
    "Work Chat": "你是一个简洁的技术助手，只说要点"
    "闲聊": "你是一个轻松友好的聊天伙伴"
  discord:
    "bug-reports": "你是一个专业的 QA 工程师"

3. 手机端快速指令

Telegram/Discord 上给 bot 发简短指令：

/status         → 当前在看板上有什么任务
/tasks          → 我有哪些未完成的任务
/summary        → 当前项目进度摘要
/kanban ls      → 列出看板任务

这些是 Hermes 内置的 slash commands，Gateway 自动注册。

五、Gateway 管理

# 服务管理
hermes gateway start             # 启动
hermes gateway stop              # 停止
hermes gateway restart           # 重启
hermes gateway status            # 查看状态
hermes gateway run               # 前台运行（调试用）
hermes gateway install           # 安装为系统服务
hermes gateway uninstall         # 卸载系统服务

# 查看所有 profiles 的 gateway 状态
hermes gateway list

# Gateway 日志
hermes logs                      # 查看 Hermes 日志

六、注意事项

Gateway 需要长期运行

• 建议装在服务器或长期开机的机器上
• 用 hermes gateway install 装成系统服务（自动开机启动）
• 你的 MacBook 合盖后 Gateway 会断

各平台需要的 token

安全建议

security:
  allow_private_urls: false      # 禁止 bot 访问内网资源
  redact_secrets: true           # 日志中隐藏敏感信息

七、常见问题

Q: 为什么 Telegram 上发了消息没反应？ A: Gateway 没运行。检查 hermes gateway status。

Q: CLI 和 Telegram 上看到的状态不一致？ A: CLI 是直接连接，Telegram 通过 Gateway 转发。检查 Gateway 日志是否有错误：hermes gateway run 看实时输出。

Q: 能不能在飞机上离线用？ A: 不能。Hermes 需要网络连接 LLM API。Gateway 也需要网络。

nacos-cli 使用手册 — 完整版

nacos-cli 是一个命令行工具，管理 Nacos 配置中心 + AI Skills 同步。

一、安装

# 一键安装（推荐）
curl -fsSL https://nacos.io/nacos-installer.sh | bash -s -- --cli

# 安装后添加 PATH
export PATH="$HOME/.nacos/bin:$PATH"

# 验证
nacos-cli --help

安装后完成的操作：

• ~/.nacos/bin/nacos-cli 二进制文件
• ~/.nacos/ 配置目录
• PATH 已写入 ~/.zshrc

二、Profile 管理

Profile = 环境配置（服务器地址、账号）。可以建多个：dev / prod / home。

创建 Profile

# 交互式（会打开编辑器让你填）
nacos-cli profile edit home

# 一行命令设置所有字段
nacos-cli profile set home \
  host=192.168.1.108 \
  port=8848 \
  username=nacos \
  password=nacos

安全说明： username、password、accessKey、secretKey、securityToken 这五个字段用 AES-256-GCM 加密后存到文件。加密密钥在 ~/.nacos-cli/key（权限 600）。

查看 Profile

nacos-cli profile list          # 列出所有 profiles
nacos-cli profile show home     # 查看某个 profile 的值
                                # 密码显示为 ******
nacos-cli profile get home host # 只看单个字段

切换默认 Profile

nacos-cli profile switch home
# 之后运行 nacos-cli 命令时不加 --profile，默认使用 home

删除 Profile

nacos-cli profile delete dev

三、配置管理（Config）

Nacos 最核心的功能：增删改查配置。

# 读取配置
nacos-cli config-get <dataId> <group>
nacos-cli --profile home config-get sa-contract.yaml GAME

# 写入配置
nacos-cli config-set <dataId> <group>              # 从 stdin 读取
nacos-cli config-set <dataId> <group> --file ./f.yaml  # 从文件读取
echo 'content' | nacos-cli config-set <dataId> <group>

# 列出配置
nacos-cli config-list
nacos-cli config-list --data-id sa-*    # 支持通配符过滤
nacos-cli config-list --page 2 --size 10

配置优先级

命令行参数 > --profile > profile switch > 环境变量 > 默认值

四、Skill 管理

Skill 三阶段生命周期

每个 Skill 经历三个阶段才能上线：

# 📤 阶段一：上传草稿（editing）
nacos-cli skill-upload ./my-skill                # 单个
nacos-cli skill-upload --all ./skills/           # 批量

# 📋 阶段二：提交审核（reviewing → reviewed）
nacos-cli skill-review my-skill
# 审核是异步的，状态从 reviewing 变为 reviewed
# 可以查看状态：
nacos-cli skill-describe my-skill

# 🚀 阶段三：发布上线（online）
nacos-cli skill-release my-skill --version 0.0.2

查看和下载

nacos-cli skill-list                              # 列表
nacos-cli skill-list --output json                # JSON 输出（脚本用）
nacos-cli skill-list --name my-skill --page 1 --size 20  # 过滤+分页

nacos-cli skill-describe my-skill                 # 详情+版本历史
nacos-cli skill-describe my-skill --output json

nacos-cli skill-get my-skill                      # 下载到 ~/.skills/
nacos-cli skill-get my-skill -o /custom/path      # 指定路径

可见性和标签

nacos-cli skill-scope my-skill --scope PUBLIC    # 公开
nacos-cli skill-scope my-skill --scope PRIVATE   # 私有（仅自己可见）
nacos-cli skill-tags my-skill --tags retail,finance  # 标签分类

五、Skill Sync（跨 Agent 同步）

Skill Sync 是最常用的功能：让多个 Agent 共用同一套 Skills。

原理

中心仓库（~/.nacos-cli/skill-sync/profiles/<profile>/skill-repo/）
    │
    ├── symlink → ~/.claude/skills/skill-a
    ├── symlink → ~/.cursor/skills/skill-a
    ├── symlink → ~/.codex/skills/skill-a
    └── symlink → ~/.hermes/skills/skill-a

磁盘上 Skill 文件只存一份在中心仓库，其他 Agent 目录都是 symlink。

本地模式（Local Mode）

不需要 Nacos 服务器，本地文件做中心。

# 添加 skill 到 sync
nacos-cli skill-sync add my-skill
nacos-cli skill-sync add --all                    # 全部

# 注册自定义 Agent 目录（nacos-cli 不认识的需要手动加）
nacos-cli skill-sync agent add hermes ~/.hermes/skills
nacos-cli skill-sync agent add workbuddy ~/.workbuddy/skills
nacos-cli skill-sync agent list

# 查看状态
nacos-cli skill-sync status

# 加完所有 skill 后启动守护进程（持续同步）
nacos-cli skill-sync start

Nacos 模式

有 Nacos 服务器时，以服务器为中央源。

nacos-cli --profile home skill-sync add --all
nacos-cli --profile home skill-sync start
# 启动后自动每 60 秒检查同步状态
# 本地有修改自动上传为 draft
# 远程有更新自动拉取到本地

解决冲突

# 查看冲突
nacos-cli skill-sync status
# 显示 Conflict 状态的 skill

# 以 Nacos 版本为准
nacos-cli skill-sync resolve my-skill --use-nacos

# 以本地某个 Agent 的版本为准
nacos-cli skill-sync resolve my-skill --use-agent codex

同步状态说明

六、你本机已完成的配置

Nacos 服务器: 192.168.1.108:8848
Profile 名称: home
已同步 Skills: 191 个
已注册 Agent: 10 个
  - codex / claude / cursor
  - openclaw / agents / hermes
  - workbuddy / qclaw / cc-switch / open-design

日常使用

# 查看同步状态
nacos-cli --profile home skill-sync status

# 加新 skill
nacos-cli --profile home skill-sync add <skill-name>

# 查看 Nacos 上的 Skills
nacos-cli --profile home skill-list

# 读/写接口契约
nacos-cli --profile home config-get sa-contract.yaml GAME
nacos-cli --profile home config-set sa-contract.yaml GAME --file ./contract.yaml

七、交互终端模式

不想每次都敲 --profile home 前缀？用交互模式：

nacos-cli -s 192.168.1.108:8848 -u nacos -p nacos

进入后支持命令：

nacos> help           # 显示所有命令
nacos> server         # 服务器信息
nacos> ns             # 当前命名空间
nacos> ns production  # 切换命名空间
nacos> skill-list     # 列出 skills
nacos> config-list    # 列出配置
nacos> clear          # 清屏
nacos> quit           # 退出

八、完整命令速查

Hermes Kanban 看板系统 — 完整手册

Kanban 是 "信号卡" 的意思。在 Hermes 里，它是一个 SQLite 任务看板，可以把大需求拆成小卡片，自动或手动派发给 worker 去执行。

一、Kanban 能解决什么问题

没有看板时，你只能靠对话来推进任务：

你：重构战斗系统
Hermes：好的我要做 A
你：还要做 B
Hermes：好的
你：别忘了 C
...

有了看板，任务变成卡片，你一目了然：

看板状态：
╔═══════════════════════════════════════╗
║  待处理          进行中        已完成   ║
║ ┌─────────┐  ┌─────────┐  ┌─────────┐║
║ │战斗系统B │  │战斗系统A │  │战斗系统C │║
║ │(等待中)  │  │(worker1)│  │(已做完)  │║
║ └─────────┘  └─────────┘  └─────────┘║
╚═══════════════════════════════════════╝

二、核心概念

看板（Board）

每个项目一个看板。比如石器时代项目一个看板，Nacos 配置项目另一个看板。

任务卡片（Task）

一个卡片 = 一件事。卡片有：标题、描述、状态、负责人、优先级、依赖关系。

任务状态流转

Scheduled ──→ Todo ──→ Ready ──→ In Progress ──→ Done
   ↑                       ↑            │
   └── 定时触发             └── blocked ─┘

依赖关系

卡片之间可以建立父子依赖：

hermes kanban link 3 1   # 任务 3 依赖任务 1
                          # 任务 1 做完后，任务 3 自动变为 Ready

三、配置

不需要改配置也能用，但了解这些可以更好地调优：

# ~/.hermes/config.yaml 中 kanban 相关配置
kanban:
  dispatch_in_gateway: true        # 让 Gateway 自动派发任务
  dispatch_interval_seconds: 60    # 每 60 秒检查一次看板
  failure_limit: 2                 # 任务失败 2 次就标记失败
  worker_log_rotate_bytes: 2097152 # worker 日志单个文件上限 2MB
  worker_log_backup_count: 1       # 保留 1 份日志备份
  orchestrator_profile: ''         # 编排器使用的 profile
  default_assignee: ''             # 默认指派给谁
  max_in_progress_per_profile: null # 每个人最多同时做几个任务（null=不限）
  auto_decompose: true             # 自动拆分子任务
  auto_decompose_per_tick: 3       # 每次派发最多拆 3 个
  dispatch_stale_timeout_seconds: 14400  # 任务超时 4 小时

四、命令行完整参考

初始化

hermes kanban init
# 创建 ~/.hermes/kanban.db，已有则跳过（幂等操作）

看板管理

hermes kanban boards list                       # 列出所有看板
hermes kanban boards create sa-game             # 新建看板
hermes kanban boards switch sa-game             # 切换到某个看板
# 切换后，后续所有命令都针对这个看板操作

创建任务

# 交互式：会依次询问标题、描述、优先级等
hermes kanban create

# 一行命令创建
hermes kanban create \
  --title "实现登录接口" \
  --body "客户端写 LoginView
服务端实现 fid=71/72
两端对齐 Nacos 契约"

# 创建 Swarm 编排任务（见下面 Swarm 章节）
hermes kanban swarm "实现登录功能" \
  --worker profile-a:UI:skill-vue \
  --verifier profile-b \
  --synthesizer profile-c

查看任务

hermes kanban list          # 列所有任务（标题+ID+状态+负责人）
hermes kanban stats         # 统计板：各状态数量 + 最老的 Ready 任务等待多久
hermes kanban show <id>     # 任务详情（描述、评论、事件历史、日志）
hermes kanban tail <id>     # 实时跟踪某个任务的进展（Ctrl+C 退出）
hermes kanban watch         # 持续看板事件流（新任务、状态变更等实时打印）

认领和指派

hermes kanban claim <id>            # 认领一个 Ready 任务给自己
hermes kanban assign <id> --profile name  # 指派给某个 profile
hermes kanban reassign <id> --profile name  # 改派
hermes kanban reclaim <id>          # 释放当前认领（让别人能认领）

状态变更

hermes kanban complete <id>         # 标记完成
hermes kanban block <id>            # 标记阻塞
hermes kanban unblock <id>          # 解除阻塞
hermes kanban promote <id>          # 手动将 Todo/Blocked 提升为 Ready
hermes kanban schedule <id>         # 转为定时任务（需配合时间条件）
hermes kanban archive <id>          # 归档（保留历史但不显示）

依赖管理

hermes kanban link 3 1       # 任务 3 依赖任务 1（1 做完后 3 自动 Ready）
hermes kanban unlink 3 1     # 解除依赖

协作

hermes kanban comment <id> --message "客户端已做完，等待服务端"  # 加备注
hermes kanban log <id>       # 查看 worker 运行日志
hermes kanban runs <id>      # 查看任务的运行历史（每次尝试、耗时、结果摘要）

任务分解（高级）

hermes kanban decompose <id>      # 自动拆成子任务，路由到不同 profiles
hermes kanban specify <id>        # 把草稿任务细化为具体规格（标题+body）

通知订阅

hermes kanban notify-subscribe <task-id> <source>   # 订阅任务完成通知
hermes kanban notify-list                            # 列出所有订阅
hermes kanban notify-unsubscribe <task-id> <source>  # 取消订阅

Swarm 编排模式

Swarm 是 Kanban 的高级模式，创建一组 并行 Worker → Verifier 审查 → Synthesizer 合并 的任务结构：

hermes kanban swarm "实现登录系统的完整前后端对接" \
  --worker profile-a:登录界面:skill-vue,skill-ui \
  --worker profile-b:登录协议客户端:skill-ts,skill-net \
  --worker profile-c:登录接口服务端:skill-node,skill-api \
  --verifier profile-d \
  --synthesizer profile-e

执行时的结构：

             "实现登录系统"
                   │
         Orchestrator 自动分解
                   │
    ┌──────────────┼──────────────┐
    │              │              │
 Worker A      Worker B      Worker C
(登录界面)    (协议客户端)   (服务端接口)
    │              │              │
    └──────────────┼──────────────┘
                   │
              Verifier D
           （审查三端一致性）
                   │
            Synthesizer E
          （合并结果，写回看板）
                   │
              任务完成 ✅

清理

hermes kanban gc     # 清理：归档任务的工作区、旧事件、旧日志

五、实际场景用法

场景：石器时代项目

# 1. 初始化
hermes kanban init
hermes kanban boards create sa-game
hermes kanban boards switch sa-game

# 2. 创建任务
hermes kanban create --title "登录模块" \
  --body "客户端 LoginView
服务端 fid=71/72
对齐 Nacos sa-contract.yaml"
hermes kanban create --title "战斗系统" \
  --body "B_SEND/fid=14 客户端发送
B_RECV 服务端 BC/BA/BU 推送"
hermes kanban create --title "地图模块" \
  --body "MC_RECV/fid=37 地图数据
MapRenderer 渲染"

# 3. 看板上现在 3 个任务，都是 Todo
hermes kanban stats
# → Todo: 3 | In Progress: 0 | Done: 0

# 4. 开始做登录模块
hermes kanban claim 1
# → 任务 1 变为 In Progress

# 5. 做完了
hermes kanban comment 1 --message "客户端登录界面完成，等待服务端联调"
hermes kanban complete 1
# → 任务 1 变为 Done
hermes kanban stats
# → Todo: 2 | In Progress: 0 | Done: 1

六、局限性

1. 只派发给 Hermes worker — Kanban 只能派发给 Hermes 自己的 profiles，不能直接派发给 Claude Code 或其他 Agent
2. SQLite 单机 — kanban.db 是本地 SQLite 文件，不能直接跨机器共享
3. 跨机器方案 — 需要把 kanban.db 放到 git 仓库或共享存储

七、常用命令速查

TPROXY 透明代理原理

什么是 TPROXY

TPROXY（Transparent Proxy）是 Linux 内核原生的透明代理技术，属于 netfilter 框架的一部分。相比传统的 REDIRECT，TPROXY 在设计上更"干净"，也是对应用层最透明的方案。

核心思路

TPROXY 不是「改目标地址」，而是给内核发一条指令：

这个包别路由出去，直接交给本机的 7893 端口处理，同时保留所有原始信息。

跟 REDIRECT 的对比

REDIRECT（你之前用的方式）

客户端 → 路由器(PREROUTING)
              │
              ▼
      iptables -j REDIRECT --to-ports 7892
              │
              │ 把目标IP:端口改了
              │ (例如: youtube.com:443 → 127.0.0.1:7892)
              ▼
      mihomo 收到连接
              │
              │ 需要用 SO_ORIGINAL_DST 从内核拿回真实目标
              │ (但拿回的是 IP，不知道原始域名)
              ▼
      DNS 污染时：拿到错误 IP → 连错服务器 → 失败

本质：内核把包"篡改"了，mihomo 得费力去猜原始目标是什么。

TPROXY（现在用的方式）

客户端 → 路由器(PREROUTING)
              │
              ▼
      iptables -j TPROXY --on-port 7893 --tproxy-mark 1
              │
              │ 不打改包，只是打个标记(fwmark=1)
              │ 原始目标 IP:端口 原封不动
              ▼
      策略路由：标记 1 的包 → 路由表 100
                                │
                                ▼
                         route add local 0.0.0.0/0 dev lo
                         (所有标记包都交给本机回环接口处理)
                                │
                                ▼
      mihomo 收到连接，直接看到原始目标 IP:端口
      配合 sniffer 读取 TLS SNI → 拿到 www.youtube.com
      即使 IP 被污染，也能从域名识别出正确目标

本质：内核不篡改包，只是"拦截并本地投递"，mihomo 看到的和客户端发送的完全一致。

三要素

TPROXY 需要三个东西同时配合才能工作：

1. iptables mangle 表规则

iptables -t mangle -A PREROUTING -p tcp -j TPROXY --on-port 7893 --tproxy-mark 1

• -t mangle：mangle 表在 PREROUTING 链处理，时机比 nat 表更早
• --on-port 7893：把匹配的包交给本机 7893 端口
• --tproxy-mark 1：给包打上标记 1，路由系统根据这个标记做策略路由

2. 策略路由

ip rule add fwmark 1 table 100
ip route add local 0.0.0.0/0 dev lo table 100

这两条的意思是：凡是打了标记 1 的包，查路由表 100。路由表 100 说：所有地址都是本机地址（local），走回环接口（lo）处理。

没有策略路由的话，内核收到一个目标为 8.8.8.8:443 的包，会试图从 WAN 口发出去，而不是交给本地进程。

3. mihomo 监听 tproxy 端口

tproxy-port: 7893

mihomo 需要用 IP_TRANSPARENT socket 选项来绑定，这要求：

• mihomo 以 root 运行（或者有 CAP_NET_ADMIN 权限）
• 这样才能接收目标不是本机的包

关键区别：为什么 TPROXY 不怕 DNS 污染

REDIRECT 场景

客户端 DNS → 阿里 DoH → 69.171.235.22(Facebook)  ← DNS 被污染
客户端 TCP → 69.171.235.22:443
REDIRECT → 改目标为 127.0.0.1:7892
mihomo 拿到 127.0.0.1:7892，用 SO_ORIGINAL_DST 问内核
内核返回 69.171.235.22:443
mihomo 连 69.171.235.22:443 → Facebook 不认识 youtube SNI → 断

TPROXY 场景

客户端 DNS → 阿里 DoH → 69.171.235.22(Facebook)  ← 同样污染
客户端 TCP → 69.171.235.22:443
TPROXY → 不打改包，打标记 1 → 策略路由 → 本机 7893
mihomo 直接看到 69.171.235.22:443（原始目标保留着）
mihomo sniffer 嗅探 TLS 握手 → SNI: www.youtube.com
mihomo 用域名规则 → DOMAIN-SUFFIX,youtube.com,🚀 节点选择 → 走代理
mihomo 自己重新解析 youtube.com（通过 Google DNS）→ 正确 IP
代理连到正确的 YouTube 服务器 → 成功

即使 IP 被 DNS 污染，TPROXY 保留了完整包信息，sniffer 能从 TLS 层拿到真实域名。

支持 UDP（REDIRECT 做不到的）

REDIRECT 只能劫持 TCP，因为 UDP 没有连接概念，改了目标地址就没法还原了。

TPROXY 可以劫持 UDP：

tproxy-port: 7893

iptables 加一条 UDP 规则：

iptables -t mangle -A PREROUTING -p udp -j TPROXY --on-port 7893 --tproxy-mark 1

mihomo 收到 UDP 包后，可以根据原始目标 IP 做 DNS 防污染、QUIC 代理等。

数据流完整路径

┌─────────────────────────────────────────────────────────────────┐
│                        客户端 (192.168.1.215)                    │
│  浏览器 → youtube.com:443                                      │
└──────────────────────────┬──────────────────────────────────────┘
                           │ 包: src=192.168.1.215:54321
                           │     dst=69.171.235.22:443
                           ▼
┌─────────────────────────────────────────────────────────────────┐
│                   路由器 (i br-lan 进入)                         │
│                                                                 │
│  ① PREROUTING (mangle, 最先处理)                                │
│     └─ MIHEMO 链: 来源 IP=215, TCP → TPROXY --on-port 7893    │
│        包没改，但打上了 fwmark=1                                 │
│                                                                 │
│  ② 路由决策                                                    │
│     └─ fwmark=1 → 查路由表 100                                 │
│        路由表 100: local 0.0.0.0/0 dev lo                       │
│        → "这是本机地址，从 lo 送本地进程"                        │
│                                                                 │
│  ③ mihomo (监听 0.0.0.0:7893, IP_TRANSPARENT)                  │
│     收到包，看到原始目标 69.171.235.22:443                       │
│     └─ sniffer 嗅探 TLS ClientHello → SNI: www.youtube.com     │
│     └─ match DOMAIN-SUFFIX,youtube.com → 🚀 节点选择            │
│     └─ 连接 35.78.84.79:10541 (VLESS Reality) 走代理           │
│                                                                 │
│  ④ 出口 (FORWARD → POSTROUTING → pppoe-wan)                    │
│     代理流量正常路由                                              │
└─────────────────────────────────────────────────────────────────┘

总结

背景

肥猫云在四月份以后改用了独立的客户端，取代了订阅模式，导致家里的每个设备都要安装客户端，太麻烦了。

官方推出了openwrt的版本，经过分析后，是一个netflow+mihomo的套壳项目。

概述

肥猫云 Lite 原包 luci-app-fcclient_3.0.7-202605210720_all.ipk 是一个 OpenWrt 路由器上的套壳代理方案，由三个组件叠加而成：

LuCI 管理界面 (Lua)
    ↕
netflow 后端 (Go binary)  ← 套壳层
    ↕
mihomo (Go binary)        ← 代理核心

组件拆解

1. 代理核心：mihomo

版本: Mihomo Meta v1.19.27 (linux arm64, go1.26.4)

负责实际的代理功能。以子进程方式运行，由 netflow 后端启动和管理。

运行参数：

mihomo -d /etc/netflow/mihomo -f <临时配置文件>

• -d /etc/netflow/mihomo — 工作目录（geoip/geosite 等数据库所在目录）
• -f <临时文件> — 配置文件由 netflow 动态生成，存放在 /tmp/.nf_*

关键特性：

• 使用 geodata 模式（geoip.dat + geosite.dat）
• 支持 VLESS Reality、Shadowsocks、Trojan 等多种协议
• 自带 RESTful API（外部控制端口 9091）
• TUN 模式支持（但默认关闭）

2. 套壳层：netflow 后端

位置: /usr/bin/netflow → 符号链接到 netflow_aarch64（Go binary，UPX 压缩） 端口: 127.0.0.1:9190 技术: Go 语言，编译为静态链接二进制，UPX 压缩减少体积

职责

配置存储

UCI 配置 (/etc/config/netflow)
  ├── netflow.config      # 基本设置（端口、模式等）
  └── netflow.v2board     # 订阅登录信息（加密存储）

文件存储
  ├── /etc/netflow/config.yaml     # mihomo 配置文件（或临时文件）
  ├── /etc/netflow/mihomo/         # mihomo 工作目录
  │   ├── mihomo                   # mihomo 二进制
  │   ├── geoip.dat                # IP 地理数据库
  │   ├── geosite.dat              # 域名分类数据库
  │   └── config.yaml              # 启动后的配置文件
  ├── /etc/netflow/v2board/
  │   └── subscribe.enc            # 加密的订阅数据
  └── /etc/netflow/.dev_salt       # 设备专属加密盐

加密机制

安装时生成 .dev_salt（32 字节随机数 → 64 位 hex）
    ↓
UCI 中存储的密码/api_url → ENC:base64(AES(salt, 明文))
    ↓
订阅数据 → subscribe.enc → AES(salt, 节点JSON)

3. 管理界面：LuCI

位置:

• 控制器: /usr/lib/lua/luci/controller/netflow.lua
• 视图: /usr/lib/lua/luci/view/netflow/main.htm
• 权限: /usr/share/rpcd/acl.d/luci-app-fcclient.json

负责在 OpenWrt 的 Web 管理界面提供操作面板，功能包括：

• 输入/修改订阅账号
• 查看连接状态
• 切换代理模式
• 触发订阅更新

RPC 权限文件定义了后端 API 的访问控制。

数据流

订阅更新流程

用户点击"更新订阅"
    ↓
LuCI → RPC → netflow 后端 (127.0.0.1:9190)
    ↓
netflow 解密 UCI 中的 api_url / token
    ↓
调用 v2board 面板 API → 获取节点列表
    ↓
AES 加密 → 写入 subscribe.enc
    ↓
解密 subscribe.enc → 生成 mihomo config.yaml
    ↓
重启 mihomo 进程

代理数据流

局域网设备
    ↓ (iptables REDIRECT / TPROXY / 手动设代理)
mihomo (7890 mixed / 7892 redir)
    ↓ (规则匹配: GEOIP / GEOSITE / DOMAIN-SUFFIX)
代理策略组 (手动 / url-test / fallback)
    ↓ (VLESS Reality 加密隧道)
节点服务器 (35.78.84.79)
    ↓
目标网站

v2board API 对接

netflow 后端实现了 v2board 面板的客户端协议：

• api/v1/passport/auth/login — 登录获取 token
• api/v1/user/getSubscribe — 获取订阅元信息
• api/v1/client/subscribe — 获取实际节点配置

关键设计缺陷

1. iptables 规则未正确配置

prerm 脚本中有 iptables 清理命令，证明 netflow 应该管理透明代理：

iptables -t nat -D PREROUTING -j NETFLOW
iptables -t nat -D PREROUTING -p dport 53 -j REDIRECT --to-ports 7874

但实际运行时 nat 表是空的。可能是：

• netflow 二进制的 UPX 压缩导致这段代码被省略了
• 或者此功能在当前版本已移除

2. 订阅加密导致配置不透明

subscribe.enc 使用设备专属 salt 加密，导致：

• 无法直接查看/修改节点配置
• 无法将订阅数据迁移到另一台设备
• mihomo 的配置文件必须由 netflow 生成，无法直接编辑

3. 节点域名依赖特殊 DNS

节点使用的域名（如 a002-lite01.llguangli25n.com）在公共 DNS 中不存在，只有通过 fcclient App 的 TUN/fake-ip 系统才能解析。路由器上的 mihomo 无法直接解析这些域名。

关键发现

订阅系统分析

• Mac App 使用新 API: fcapi.apiv2.a047.com/api/v1/passport/auth/login
• 路由器 使用旧 v2board API，返回过期节点
• 订阅元数据 API: user/getSubscribe?auth_data=JWT 返回套餐/UUID/订阅地址
• 实际节点配置服务器: fcsblka.fcsubcn.cc:2096（定制 TLS，无法从外部连接）

找到真实节点 IP

• 通过 Mac 的 netstat 观察到所有节点都连接到 35.78.84.79
• 路由器 ping 该 IP 可达 (~41ms)

获取jwt token

完整的过程在这里：

# ============================================
# 第1步：登录获取 JWT令牌
# ============================================
curl -X POST "https://fcapi.apiv2.a047.com/api/v1/passport/auth/login" \
  -H "User-Agent: fcclient/3.0.7" \
  -H "Content-Type: application/json" \
  -d '{"email":"xxxxxxxxx@gmail.com","password":"xxxxxxx"}'

# 返回结果：
{
  "status": "success",
  "data": {
    "token": "dW4h1Z87kQQ9vDHrMxxxxxxxxxxxx",
    "auth_data": "eyJ0eXAiOiJKV1QiLCJhxxxxxxxxx.eyJpZCI6MTkyOTg3LCJxxxxxxxxxzdmMGVkMGVhM2VkOWZmYWM0ZWU0NjgyZWFiOTI0NjYifQ.7WpSShJZjn2a3IvVxxxxxxxxiC79LMqLnO1xZw"
  }
}

# ============================================
# 第2步：获取订阅元信息（套餐/UUID/流量/订阅地址）
# ============================================
# 用上一步返回的 auth_data 作为 query 参数
curl "https://fcapi.apiv2.a047.com/api/v1/user/getSubscribe?auth_data=eyJ0eXAiOiJKV1QixxxxxxxJ9.eyJpZCI6MTkyOTg3LCJzZXNzxxxxxxxxGVkMGVhM2VkOWZmYWM0ZWU0xxxxxx0NjYifQ.7WpSShJZjn2a3IvVxxxxxxxxC79LMqLnO1xZw" \
  -H "User-Agent: fcclient/3.0.7"

# 返回结果：
{
  "status": "success",
  "data": {
    "plan_id": 5,
    "token": "dW4h1Z87kQQ9vDHrMgzrmDBlGrDIo3Gm",
    "expired_at": 1825999987,
    "u": 394537826,
    "d": 7870981628,
    "transfer_enable": 64424509440,
    "email": "xxxxxxxxx@gmail.com",
    "uuid": "5xxxxx7-cxxx2-4xxe-89xxx7-67dbbxxxx2",
    "plan": { "name": "肥猫小包", "id": 5, "transfer_enable": 60 },
    "subscribe_url": "https://fcsblka.fcsubcn.cc:2096/api/v1/client/subscribe?token=dW4h1Z87kQQ9vDHrMgzrmDBlGrDIo3Gm",
    "reset_day": 24
  }
}

最终方案

架构

去掉netflow，直接使用mihomo作为透明代理

局域网设备 → 路由器 (iptables 透明代理) → mihomo → 35.78.84.79 (VLESS Reality 节点) → 外网

配置要点

• 60 个 VLESS Reality 节点 (HK20/TW10/SG10/JP10/US10)，全部指向 35.78.84.79
• 策略组: 🚀 节点选择(手动) / 自动选择(url-test) / 故障转移(fallback)
• 规则: .cn/GEOIP 直连，google/github/youtube 走代理，其余兜底代理
• Web 面板: http://192.168.1.1/yacd/ (Yacd-meta)，API 密钥 netflow_secret

部署的文件

命令速查

# mihomo 服务管理
/etc/init.d/mihomo start|stop|restart|status
/etc/init.d/mihomo enable|disable  # 开机自启

# 透明代理
/root/tproxy.sh start|stop|status|restart

# 查看日志
logread -e mihomo
cat /tmp/netflow_mihomo.log

# Web 面板
http://192.168.1.1/yacd/   # 连接 192.168.1.1:9091 密钥 netflow_secret

# 添加规则 (sed 免 vi)
sed -i '/DOMAIN-SUFFIX,google.com/i\  - DOMAIN-SUFFIX,baidu.com,DIRECT' /etc/netflow/mihomo/config.yaml
/etc/init.d/mihomo restart

容错机制

待办/风险

• 35.78.84.79 可能是动态 IP，失效后需重新获取
• 订阅数据无法直接获取，依赖 Mac 抓包找 IP
• dnsmasq 上游配置 127.0.0.1#7874 如需调整

对比：我们最终的路由器方案

my-edge-blog 项目文档

概览

一个部署在 Cloudflare Workers 上的个人博客系统，纯服务端渲染（SSR），支持多主题切换、管理后台、Markdown 渲染、暗色模式等。共 5,495 行代码。

技术栈

完整功能清单

前端（4 套主题）

管理后台

安全措施

数据库表结构

-- 文章表
posts (id, slug, title, summary, content, cover_image, tags, category,
       published, created_at, updated_at, view_count)

-- 评论表（已建表，待开发）
comments (id, post_id, author, content, created_at)

-- 置顶帖子
pinned_posts (id, post_id, sort_order, created_at)

-- 站点设置
settings (key, value)

-- 社交链接
social_links (id, label, url, icon, sort_order, created_at)

源码结构

my-edge-blog/
├── src/
│   ├── index.ts        (143行) 入口、认证路由、安全中间件
│   ├── routes.ts       (273行) 公开路由（首页/文章/搜索/RSS/sitemap/robots）
│   ├── admin.ts        (310行) 管理后台 CRUD + 主题/设置/上传
│   ├── db.ts           (392行) D1 查询封装 + 内存缓存层
│   ├── auth.ts         (19行) 共享认证模块
│   ├── marked.ts       (46行) Marked 配置 + 自定义渲染器
│   └── templates.tsx   (2147行) 所有 JSX 模板（4主题 Layout + Page）
├── public/
│   ├── common.css      (577行) 共享样式
│   ├── theme-loveit.css     (451行)
│   ├── theme-papermod.css   (354行)
│   ├── theme-minimal.css    (345行)
│   ├── theme-tech.css       (438行)
│   └── robots.txt
├── migrations/ (6 个 SQL 迁移文件)
├── schema.sql          (完整建表 SQL)
├── wrangler.jsonc      (Cloudflare Workers 配置)
├── tsconfig.json       (TypeScript 配置)
└── package.json        (依赖配置)

路由表

部署文档（从头手搓）

前置条件

# 1. 安装 Node.js 18+
# 2. 安装 Wrangler CLI
npm install -g wrangler
# 3. 登录 Cloudflare
wrangler login

项目初始化

# 1. 创建项目目录
mkdir my-edge-blog && cd my-edge-blog

# 2. 初始化项目
npm init -y
npm install hono marked marked-highlight highlight.js
npm install -D wrangler @types/node

# 3. 配置 tsconfig.json
{
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "hono/jsx",
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "strict": true,
    "skipLibCheck": true,
    "lib": ["ESNext"]
  }
}

创建 Cloudflare 资源

# 1. 创建 D1 数据库
wrangler d1 create notion-d1

# 2. 创建 R2 存储桶
wrangler r2 bucket create notion-r2

# 3. 创建 KV namespace
wrangler kv:namespace create ADMIN_KV

# 4. 设置管理员密码
wrangler secret put ADMIN_PASSWORD

配置 wrangler.jsonc

将 d1_databases、r2_buckets、kv_namespaces 中的 ID 替换为上一步创建的值。

数据库初始化

wrangler d1 execute notion-d1 --file schema.sql
# 再依次执行所有 migrations/*.sql

本地开发

npm run dev
# 启动 http://localhost:8787
# 连接生产资源: npx wrangler dev --remote

部署

npm run deploy
# = wrangler deploy --minify

项目亮点

• 零外部 Frontend 框架 — 纯 Hono JSX SSR
• 零 CSS 框架 — 原生 CSS + 自定义属性
• 全站 SSR — 首屏极速
• 多主题架构 — 通过 Layout() 分发函数，新增主题只需加一个函数
• 内存缓存层 — 60s TTL 减少 D1 查询次数
• 边缘部署 — Cloudflare Workers 全球 300+ 节点

Git 新手教程

一、基础概念

Git 是什么？

Git 是分布式版本控制系统。每次提交（commit）就像游戏存档，随时可以回档。

三个区域

工作区 (Working Directory)    →    暂存区 (Staging Area)    →    仓库 (Repository)
   你正在编辑的文件              git add 之后               git commit 之后

文件状态

二、安装与初始配置

# 安装（Mac 推荐 brew）
brew install git

# 必做的全局配置
git config --global user.name "你的名字"
git config --global user.email "你的邮箱"

# 查看配置
git config --list

# 设置默认分支名（推荐 main 而非 master）
git config --global init.defaultBranch main

三、常用命令速查

🏗️ 创建仓库

# 从零开始
git init

# 克隆远程仓库
git clone https://github.com/user/repo.git

# 克隆到指定目录
git clone https://github.com/user/repo.git my-folder

📝 日常三步曲：add → commit → push

# 1. 查看当前状态
git status

# 2. 把修改加入暂存区
git add file.py              # 添加单个文件
git add .                    # 添加所有修改

# 3. 提交
git commit -m "描述你改了什么"

# 4. 推送到远程
git push

# 一句话搞定（已跟踪文件的修改）
git commit -am "修复登录bug"

📥 拉取更新 (git fetch 完全指南)

核心区别：

• git pull = git fetch + git merge（一步到位）
• git fetch = 只下载远程最新数据，不会自动合并
• 先用 fetch 看远程有什么变化，再决定怎么合并——更安全可控

# 最常用
git pull                       # 拉取并自动合并（一步到位）

# 更安全的做法：先看再合
git fetch                      # 只下载，不合并
git log --oneline main..origin/main  # 看看远程有哪些新提交
git merge origin/main          # 确认没问题后再合并

基础用法

# 从默认远程（origin）拉取
git fetch

# 从指定远程拉取
git fetch origin
git fetch upstream             # 如果有多个远程

# 从所有远程拉取
git fetch --all

拉取特定分支

# 拉取远程的某个分支
git fetch origin main          # 只拉取 main 分支
git fetch origin feature/login # 拉取指定功能分支

# 拉取后查看远程分支
git branch -r                  # 查看所有远程分支
# origin/main
# origin/feature/login

# 基于远程分支创建本地分支
git switch -c login origin/feature/login

清理远程分支信息

# 远程已删除的分支，本地还残留在 remote 列表里
git branch -r                  # 可能看到 origin/old-feature

# 清理已不存在的远程分支
git fetch --prune
# 或简写
git fetch -p

# 同时拉取并清理
git fetch --all --prune

# 查看清理效果
git branch -r                  # 已删除的远程分支不再显示

安全 fetch 的技巧

# 先 fetch 看看远程情况
git fetch origin
git status                     # 提示：Your branch is behind 'origin/main' by 3 commits

# 查看远程新提交的内容（不合并就不会冲突）
git log --oneline main..origin/main
# 或看 diff
git diff main origin/main

# 确认可以合并后再操作
git merge origin/main          # 快进合并（fast-forward）

# 如果不想 merge，也可以 rebase
git rebase origin/main

强制覆盖本地（谨慎使用）

# 场景：本地已经改乱了，想完全重置为远程版本
git fetch origin
git reset --hard origin/main  # ⚠️ 会丢弃所有本地修改！

多远程协同

# 查看所有远程
git remote -v
# origin    https://github.com/你自己/repo.git (fetch)
# upstream  https://github.com/原作者/repo.git (fetch)

# 从不同远程拉取
git fetch upstream            # 拉取原作者的更新
git log --oneline main..upstream/main  # 和原作者有哪些差异
git merge upstream/main       # 合并到本地

💡 最佳实践： 养成先 git fetch 再决定合并方式的习惯，而不是直接用 git pull。fetch 让你有机会在合并前检查远程的改动，避免被意外的合并冲突打个措手不及。

🔀 分支操作

# 查看分支
git branch                   # 本地分支
git branch -a                # 包含远程分支

# 创建并切换分支
git checkout -b feature-login
# 或新版语法
git switch -c feature-login

# 切换分支
git checkout main
# 或
git switch main

# 合并分支（先切到目标分支）
git switch main
git merge feature-login

# 删除分支
git branch -d feature-login  # 已合并的
git branch -D feature-login  # 强制删除

🔍 查看历史 (git log 完全指南)

# 最常用
git log
git log --oneline            # 简洁版（一行一条）
git log --oneline --graph    # 带 ASCII 分支图

格式化输出

# 自定义格式
git log --format="%h - %an: %s"
# %h = 短 hash, %an = 作者, %s = 标题, %ad = 日期

# 内置漂亮格式
git log --pretty=format:"%C(yellow)%h%Creset %C(cyan)%ad%Creset %s" --date=short

# 显示分支拓扑图（必学！）
git log --oneline --graph --all --decorate

按条件过滤

# 按作者
git log --author="张三"
git log --committer="李四"

# 按时间
git log --since="2025-01-01"
git log --until="2025-06-01"
git log --since="2 weeks ago"
git log --since="yesterday"

# 按提交信息
git log --grep="修复"
git log --grep="feat" --grep="fix" --all-match  # 同时匹配多个

# 按文件
git log -- app/models/user.rb      # 只看某个文件的历史
git log -p app/models/user.rb      # 同时看每个版本的 diff

查看变更内容

git log -p                     # 每次提交的完整 diff
git log --stat                 # 统计改了多少文件，多少行
git log --name-only            # 只看改了哪些文件
git log --name-status          # 文件及变更类型（A/M/D）

限制输出数量

git log -5                     # 只看最近 5 条
git log -n 10                  # 同上
git log --max-count=20

# 只看某个范围内的提交
git log main..feature          # feature 有但 main 没有的提交
git log --since="2025-01-01" --until="2025-03-01" -10

分支对比

# 查看两个分支的差异提交
git log main..feature          # feature 有而 main 没有
git log --oneline --left-right main...feature  # 两侧对比

# 查看分支的合并关系
git log --oneline --graph --merges

高级用法

# 搜索包含特定字符串的提交
git log -S "console.log"          # 新增或删除该字符串的提交
git log -G "console.log"          # 匹配正则的提交（比 -S 更广）

# 查看某个函数的修改历史
git log -L :functionName:file.py

# 查看所有分支的提交（不只是当前分支）
git log --all --oneline

# 只看合并提交
git log --merges
git log --no-merges             # 排除合并提交

# 自定义漂亮输出（推荐配置别名）
git log --graph --pretty=format:'%C(yellow)%h%Creset %C(blue)%d%Creset %s %Cgreen(%cr) %C(cyan)<%an>%Creset' --all

💡 建议配置别名： git config --global alias.lg "log --graph --pretty=format:'%C(yellow)%h%Creset %C(blue)%d%Creset %s %Cgreen(%cr) %C(cyan)<%an>%Creset' --all"，之后用 git lg 即可享受漂亮的日志展示。

# 查看谁改了什么（不是 log，但常一起用）
git blame file.py

↩️ 撤销操作

# 撤销工作区修改（还没 add）
git restore file.py
# 或旧语法
git checkout -- file.py

# 撤销暂存（已 add，还没 commit）
git restore --staged file.py
# 或旧语法
git reset HEAD file.py

# 撤销最近一次提交（保留修改）
git reset --soft HEAD~1

# 撤销最近一次提交（丢弃修改）⚠️ 危险
git reset --hard HEAD~1

# 修改最近一次提交信息
git commit --amend -m "新的提交信息"

🏷️ 标签

git tag v1.0                 # 轻量标签
git tag -a v1.0 -m "版本1.0" # 附注标签
git push origin v1.0         # 推送标签

四、场景实战

场景 1：第一次参与项目

# 1. 克隆仓库
git clone https://github.com/team/project.git
cd project

# 2. 创建自己的功能分支
git switch -c feature/my-feature

# 3. 写代码...然后提交
git add .
git commit -m "添加用户注册功能"

# 4. 推送到远程
git push -u origin feature/my-feature

# 5. 在 GitHub/GitLab 上创建 Pull Request (PR)

场景 2：正在开发，同事已经合了代码

# 方法一：rebase（保持线性历史，推荐）
git fetch origin
git rebase origin/main

# 方法二：merge（保留合并记录）
git fetch origin
git merge origin/main

场景 3：写了一半突然要修紧急 bug

# 方案一：stash（临时存放）
git stash                    # 保存当前修改
git switch -c hotfix/bug-123 # 切到新分支修 bug
# ...修完...
git commit -am "修复 #123"
git switch feature/my-feature # 回来继续
git stash pop                 # 恢复之前的修改

# 方案二：worktree（另一个目录工作）
git worktree add ../hotfix hotfix/bug-123
cd ../hotfix
# ...修完...
git commit -am "修复 #123"

场景 4：提交信息写错了

# 改最近一条
git commit --amend -m "正确的提交信息"

# 已经 push 了？需要强制推送（慎用）
git push --force-with-lease

场景 5：不小心把不该提交的文件 push 了

# 从仓库删除但保留本地文件
git rm --cached secret.key
git commit -m "移除敏感文件"
git push

# ⚠️ 敏感信息（密码、密钥）已推送到远程的，必须立即轮换！
# Git 历史中仍可看到，彻底清理需用 git filter-branch 或 BFG

场景 6：合并冲突

git merge feature-login
# 出现冲突时：
# 1. 打开冲突文件，找到 <<<<<<< ======= >>>>>>> 标记
# 2. 手动选择保留哪部分代码
# 3. 保存后
git add .
git commit -m "解决合并冲突"

冲突标记示例：

# <<<<<<< HEAD (当前分支)
name = "Alice"
# =======
name = "Bob"
# >>>>>>> feature-login (要合并的分支)

场景 7：回退到某个历史版本

# 查看历史
git log --oneline
# a1b2c3d 修复登录bug
# e4f5g6h 添加注册功能
# i7j8k9l 初始提交

# 回退（保留修改在工作区）
git reset --soft a1b2c3d

# 回退（彻底丢弃）⚠️
git reset --hard a1b2c3d

# 更安全的做法：用 revert 创建一个反向提交
git revert e4f5g6h

五、团队分工模式

模式 1：集中式（Centralized Workflow）

最简单，适合小团队（2-5人）。

所有人 → main 分支 → push/pull

规则：

• 只有一个 main 分支
• pull → 改代码 → push
• 冲突时先 pull 再 push

问题： 容易互相覆盖，不推荐超过 3 人使用。

模式 2：Feature Branch（功能分支模式）⭐ 最常用

main ────────────────────────────── merge ──
  └── feature-A ── merge ──┘
  └── feature-B ──────────── merge ──┘

规则：

• main 分支永远可部署
• 每个功能/任务开新分支
• 完成后通过 PR/MR 合入 main
• 合并前需要 Code Review

命名规范：

feature/用户注册
feature/payment
bugfix/登录失败
hotfix/生产环境崩溃
chore/更新依赖

模式 3：Git Flow

适合有明确发布周期的项目（如 App 发版）。

main       ────────────────────── v1.0 ──── v2.0 ──
develop    ────────────────────────────────────────
  └── feature/A ── merge to develop ──┘
  └── release/1.0 ── merge to main + develop ─┘
  └── hotfix/xxx ── merge to main + develop ─┘

分支说明：

模式 4：GitHub Flow / Trunk-Based

适合持续部署的 Web 项目，最轻量。

main ─────────────────────────────────
  └── feature ── PR + review ── merge ── 立即部署

规则：

• main 始终可部署
• 功能分支开发 → PR → Review → 合并 → 自动部署
• 没有 release 分支，持续集成

模式 5：Forking Workflow

适合开源项目，贡献者没有主仓库写权限。

主仓库 (upstream)
  ↑ PR
贡献者的 Fork (origin)
  └── feature ── push to origin ── PR to upstream

# 1. Fork 仓库（GitHub 上点按钮）
# 2. 克隆自己的 fork
git clone https://github.com/你/repo.git

# 3. 添加上游仓库
git remote add upstream https://github.com/原作者/repo.git

# 4. 同步上游更新
git fetch upstream
git merge upstream/main

# 5. 推送到自己的 fork
git push origin feature/xxx

# 6. 在 GitHub 上创建 PR

六、工作中常见情况

1. 代码审查 (Code Review)

# 提交 PR 前先同步最新代码
git fetch origin
git rebase origin/main

# 如果 PR 评审后需要修改
# 在原分支继续改，然后
git add .
git commit -m "根据 review 修改"
git push

# 或者用 amend 追加到上一个提交（保持 PR 干净）
git add .
git commit --amend --no-edit
git push --force-with-lease

2. CI/CD 流水线

push → 触发 CI → 跑测试 → 通过才能 merge

常见 CI：GitHub Actions、GitLab CI、Jenkins

3. .gitignore 文件

# 忽略不需要跟踪的文件
node_modules/
dist/
.env
*.log
.DS_Store
__pycache__/

4. SSH Key 配置（免密码推送）

# 生成 SSH Key
ssh-keygen -t ed25519 -C "your@email.com"

# 复制公钥
cat ~/.ssh/id_ed25519.pub
# 粘贴到 GitHub → Settings → SSH Keys

# 测试连接
ssh -T git@github.com

# 仓库使用 SSH URL
git remote set-url origin git@github.com:user/repo.git

5. 多人协作的礼仪

6. Commit Message 规范（Angular 规范）

<type>(<scope>): <subject>

<body>

<footer>

type 类型：

示例：

feat(auth): 添加 OAuth2 登录支持

实现 GitHub 和 Google OAuth2 登录流程，
支持自动创建账号和关联已有账号。

Closes #123

七、速查脑图

git init / clone
    │
    ├── git add . ─── git commit -m "msg" ─── git push
    │                                              │
    │                         git pull ←────────────┘
    │
    ├── git branch / switch / merge
    │
    ├── git stash ─── git stash pop
    │
    ├── git log / diff / status
    │
    ├── git restore / reset / revert
    │
    └── git remote / fetch / pull

八、推荐资源

• 交互式学习：Learn Git Branching（可视化理解分支）
• 官方文档：git-scm.com
• 速查表：GitHub Git Cheat Sheet

石器时代 8.5 原版游戏代码结构分析报告 一、项目总体结构 stoneage/ ├── client-8.5/ # 客户端源码 (Visual Studio 项目, C++) ├── server-8.5/ # 服务端源码 (Linux/C, gcc 编译) │ ├── gmsv/ # 游戏主服务端 │ └── saac/ # 账号/数据中心服务端 ├── 客户端lua文件/ # 客户端 Lua 脚本 ├── 服务器端lua文件/ # 服务端 Lua 脚本 ├── setup.cf # 服务端主配置文件 ├── acserv.cf # 账号服务端配置 ├── CSA.sql # 数据库建表 SQL └── sql.cf # SQL 配置 二、客户端代码结构 (client-8.5/client_source_code) 2.1 核心目录 目录 用途 关键文件 system/ 核心游戏系统 (57个源文件) gamemain.cpp, netmain.cpp, login.cpp, map.cpp, battleproc.cpp, menu.cpp, pc.cpp, character.cpp, chat.cpp systeminc/ 核心头文件 (58个头文件) pc.h, character.h, map.h, battleproc.h, menu.h, version.h, netmain.h oft/ 动画/渲染系统 oft.cpp(动画管理), work.cpp(工作函数), pat_dat.cpp ohta/ 高层任务处理 ohta.cpp, ohta_proc.cpp wgs/ 网络加密通信层 message.cpp(消息格式), descrypt.cpp(加密解密), tea.cpp(TEA加密), Ping.cpp newproto/ 协议层 protocol.cpp/h(516行,220+协议定义), autil.cpp/h(协议工具) mylua/ 客户端 Lua 引擎 winlua.cpp, sa.cpp, lssproto.cpp, ServerList.cpp other/ 辅助工具 trade.cpp(交易), ItemsMall.cpp(商城), GetMacAddress.h, md5_encrypt.cpp sdk/ 外部 SDK (DirectX等) curl/ HTTP 库 libcurl openssl/ 加密库 MD5等 detours/ Hook 库 Microsoft Detours 2.2 客户端核心数据结构 (pc.h) 玩家角色 (PC) 结构体 — 这是最核心的数据结构: PC { // 基础属性 graNo, faceGraNo // 图形编号 id, dir // ID, 方向 hp, maxHp, mp, maxMp // 生命值, 魔法值 vital, str, tgh, dex // 体力, 力量, 韧性, 敏捷 exp, maxExp, level // 经验, 等级 atk, def, quick, charm, luck // 攻防速魅幸 earth, water, fire, wind // 四元素属性 gold // 金币 // 物品系统 item[MAX_ITEM] // 道具栏 (5装备位+15背包×3页) itempool[MAX_ITEM] // 寄放道具 // 宠物系统 battlePetNo // 战斗出战宠物 selectPetNo[5] // 选择的5只宠物 mailPetNo // 邮件宠物 // 社交系统 familyName // 家族名 channel // 频道 trade_confirm // 交易确认状态 // 家族系统 familyleader // 家族职务 familySprite // 家族精灵(庄园) big4fm // 四大庄园标识 // 职业系统 (7.0+) profession_class // 职业类型(战士/法师/猎人) profession_level // 职业等级 profession_skill_point // 技能点 // 其他系统 ridePetNo, ridePetName // 骑宠 transmigration // 转生次数 titleNo // 称号编号 status, etcFlag // 状态/标志位 } 宠物 (PET) 结构体: PET { graNo, hp, maxHp, mp, maxMp exp, maxExp, level atk, def, quick, ai earth, water, fire, wind // 四元素 maxSkill, trn(转生数), fusion(融合标志) name, freeName, useFlag item[MAX_PET_ITEM] // 宠物装备(头/翼/牙/身/背/爪/脚) } 装备栏位枚举: 装备: HEAD, BODY, ARM, DECORATION1, DECORATION2, BELT, SHIELD, SHOES, GLOVE (共9个栏位) 宠物装备: HEAD, WING, TOOTH, PLATE, BACK, CLAW, FOOT (7个栏位) 2.3 客户端核心文件功能 文件 行数 功能 gamemain.cpp 1484 游戏主循环,帧率控制,状态机管理 login.cpp 21687 最大文件 — 登录流程,角色创建/选择/删除,服务器选择 menu.cpp 22835 第二大文件 — 所有UI菜单(状态/道具/宠物/技能/交易/银行/邮件等) map.cpp 6157 地图渲染,移动,碰撞检测,视野管理 pc.cpp 1681 玩家数据管理,属性初始化,宠物/道具/技能管理 battleproc.cpp 1172 战斗流程控制,遇敌,战斗动画 character.cpp 4051 角色对象管理(包括NPC/玩家/宠物的显示) chat.cpp 1567 聊天系统(多频道,聊天历史,屏蔽词) netmain.cpp 661 网络连接管理,Socket操作 field.cpp - 大地图渲染(地面物件) pattern.cpp - 角色动作帧管理 save.cpp - 存档系统 三、服务端代码结构 (server-8.5/gmsv) 3.1 核心模块 目录/文件 文件数 功能 battle/ 10 战斗系统(battle.c 11328行!, battle_command.c 1251行, battle_ai.c, battle_item.c, battle_magic.c, pet_skill.c, profession_skill.c) char/ 25 角色系统(char.c 11543行!, char_base.c 4559行, char_walk.c, char_talk.c, char_item.c, char_party.c, trade.c 24个源文件, pet.c, pet_event.c, family.c, skill.c, title.c, encounter.c, enemy.c, chatroom.c, addressbook.c) item/ 5 物品系统(item.c 2502行, item_event.c, item_gen.c) magic/ 5 魔法系统(magic.c 916行, magic_base.c, magic_field.c) npc/ 77 NPC系统(77个NPC类型!) map/ 5 地图系统(map_deal.c, map_util.c, readmap.c, map_warppoint.c) lua/ 193 LuaJIT 引擎完整源码 mylua/ 25 服务端 Lua 绑定层 npc_lua/ 18 NPC Lua 接口(npc_lua_battle.c, npc_lua_char.c, npc_lua_item.c, npc_lua_map.c, etc.) include/ 152 所有头文件 3.2 服务端核心文件 文件 行数 功能 lssproto_serv.c 3894 协议处理核心 — 解码客户端消息,分发到各处理函数 char.c 11543 角色管理主文件(登录,登出,行走,物品使用,交易,家族等) char_base.c 4559 角色基础数据管理(骑宠表296条!) battle.c 11328 战斗引擎(回合制,伤害计算,AI,状态效果等) battle_command.c 1251 战斗指令解析(攻击/防御/捕捉/逃跑/宠物/物品等) item.c 2502 物品数据管理(属性,类型,装备效果) magic.c 916 魔法使用逻辑(回复/属性变化/状态/复活/攻击魔法) main.c - 服务端入口,主循环 net.c - 网络层(epoll) epollnet.c - epoll 网络模型 callfromcli.c - 客户端消息处理入口 callfromac.c - 账号服务器消息处理入口 configfile.c - 配置文件解析 3.3 服务端核心数据结构 角色(Char) 结构体 — 对应客户端PC,包含更丰富的服务端逻辑字段: Char { // 基础数据: id, name, hp, mp, str, tgh, dex, etc. // 位置: floor, x, y, dir // 战斗: battleindex, battlemode // 家族: fmindex, fmrank, fmsprite // 职业: profession_class, profession_level // NPC特有: whichtype, npcworkint[10], npcarg } 战斗(BATTLE) 结构体: BATTLE { type (P_vs_E, P_vs_P, E_vs_E, WATCH, DP_BATTLE, BOSS_BATTLE) mode (NONE, INIT, BATTLE, FINISH, STOP, WATCHBC...) flg (状态标志) entry[BATTLE_ENTRY_MAX] // 最多10(或12)个参战单位 } 四、协议设计和网络通信 4.1 协议架构 协议层由三部分组成:

1. WGS层 (wgs/): 底层通信 — 消息格式化(message.cpp),TEA加密(tea.cpp),DES加密(descrypt.cpp)
2. LSS层 (lssproto): RPC协议层 — 客户端lssproto_cli.cpp + 服务端lssproto_serv.c
3. 新协议层 (newproto/): 增强协议 — protocol.cpp/h中定义的 SaDispatchMessage 4.2 协议列表 (220+ 条协议) 按功能分类: 移动/地图类: 编号 协议 方向 0-1 W/W2 S→C

2 XYD C→S 3-4 EV C↔S 42-43 CA/CD S→C 37-39 MC/M/M S→C/C→S/S→C 70 SP C→S 战斗类: 编号 协议 方向 12-13 RS/RD S→C 14-15 B C↔S 16 SKD C→S 54-55 KS C↔S 93-94 FM C↔S 97 BM C→S 107 PETST C↔S 103-104 CS C↔S 物品/装备类: 编号 协议 方向 22 I S→C 23 MI C→S 24 SI S→C 17 ID C→S 18 PI C→S 19-20 DI/DG C→S 21 DP C→S 127 PET_ITEM C→S 角色/社交类: 编号 协议 方向 25-26 MSG C↔S 27 PMSG C→S 28 PME S→C 29-33 AB/ABI/DAB/AAB C↔S 34 L C→S 35-36 TK C↔S 40-41 C C↔S 44 R S→C 登录/角色管理类: 编号 协议 方向 71-72 CLIENTLOGIN C↔S 73-74 CREATENEWCHAR C↔S 75-76 CHARDELETE C↔S 77-78 CHARLOGIN C↔S 79-80 CHARLIST C↔S 81-82 CHARLOGOUT C↔S 魔法/技能类: 编号 协议 方向 50-51 HL C↔S 52-53 PR C↔S 56 AC C→S 57 MU C→S 58-59 PS C↔S 101 NC S→C 110-111 BATTLESKILL C↔S 扩展系统类: 编号 协议 方向 95 WO S→C 112-113 CHATROOM C↔S 116-117 STREET_VENDOR C↔S 120-121 JOBDAILY C↔S 122-123 TEACHER_SYSTEM C↔S 126 FIREWORK S→C 128 MOVE_SCREEN S→C 131-132 THEATER C↔S 133-134 MAGICCARD S→C 139-140 PKLIST C↔S 141 SIGNDAY C→S 200 DENGON S→C 201-202 SAMENU C↔S 208-209 SHOPOK C↔S 210-211 FAMILYBADGE C↔S 212-213 CHARTITLE C↔S 218-219 VB C↔S 220 RIDEQUERY C→S 221-222 PETSKINS C↔S 4.3 通信机制

• 传输层: TCP Socket (非阻塞, epoll)
• 加密: TEA加密 + DES加密 + 个人密钥(PersonalKey)
• 消息格式: &;[PID];[参数计数];[参数1];[参数2];...& (8字节对齐)
• 连接模式: WGS中转服务 → 游戏服务器直连
• 账号验证: SAAC (StoneAge Account Center) 独立服务, MySQL存储 五、NPC 系统 (77个NPC类型) NPC类型 文件 商店类 npc_itemshop.c, npc_petshop.c, npc_petskillshop.c, npc_vipshop.c, npc_newvipshop.c, npc_simpleshop.c, npc_poolitemshop.c, npc_itemchange.c 传送类 npc_warp.c, npc_warpman.c, npc_transerman.c, npc_bus.c, npc_ship.c, npc_airplane.c 家族类 npc_familyman.c, npc_fmpkman.c, npc_fmpkcallman.c, npc_fmwarpman.c, npc_fmhealer.c, npc_fmletter.c, npc_fmdengon.c, npc_fmchallenge.c, npc_manorsman.c 娱乐类 npc_gamblemaster.c, npc_gambleroulette.c, npc_gamblebank.c, npc_quiz.c, npc_janken.c, npc_magiccard.c, npc_luckyman.c 功能类 npc_healer.c, npc_savepoint.c, npc_bankman.c, npc_exchangeman.c, npc_makepair.c, npc_riderman.c, npc_doorman.c 战斗类 npc_npcenemy.c, npc_autopk.c, npc_duelranking.c 宠物类 npc_petmaker.c, npc_petracemaster.c, npc_petracepet.c, npc_petfusion.c, npc_freepetskillshop.c 社交类 npc_signboard.c, npc_storyteller.c, npc_mic.c, npc_msg.c, npc_dengon.c, npc_charm.c, npc_bodylan.c 系统类 npc_sysinfo.c, npc_timeman.c, npc_scheduleman.c, npc_checkman.c, npc_roomadminnew.c 导师类 npc_transmigration.c 摆摊类 npc_pauctionman.c 日常类 npc_welfare.c, npc_dayaction.c 六、核心游戏功能特性总结 6.1 角色系统
• 属性体系: HP/MP/体力/力量/韧性/敏捷/攻/防/速/魅/幸
• 四元素: 地/水/火/风(相互克制)
• 转生系统: 最高支持6转,每次转生属性重置并成长
• 职业系统 (7.0+): 战士/法师/猎人三大职业,26级职业等级上限
• 称号系统: 图形称号 + 文字称号
• 装备栏位: 头/身/臂/装饰×2/腰带/盾/鞋/手套 = 9个 6.2 宠物系统
• 携带: 最多5只宠物
• 战斗: 宠物可出战(前后排)
• 骑乘: 296种骑宠组合表,骑宠有等级和转生要求
• 融合/进化: 宠物融合系统(人龙进化)
• 宠物装备: 7个装备栏位(头/翼/牙/身/背/爪/脚)
• 宠物技能: 大量被动/主动技能
• 宠物祝福: buff系统
• 宠物皮肤: 皮肤更换系统 6.3 战斗系统
• 模式: 遇敌制(步数触发),回合制
• 类型: PVE/PVP/观战/DP赛/BOSS战
• 阵容: 标准5v5,可扩展至6v6或40人
• 指令: 攻击/防御/捕捉/逃跑/道具/技能/宠物出退
• 宠物技能: 50+种技能(连续攻击/蓄力攻击/守护/抢夺/状态变化等)
• 职业技能: 战士/法师/猎人各有独特技能树
• 魔法: 回复/属性变化/状态变化/复活/攻击魔法/变身/召唤龙
• AI: 自动战斗AI系统
• 观战: 可观看他人战斗
• 异常状态: 中毒/麻痹/睡眠/石化/混乱/醉酒/沉默 6.4 物品系统
• 类型: 拳/斧/棍/矛/弓/盾/头盔/铠甲/手镯/脚链/项链/戒指/腰带/耳环/鼻环/护身符/回旋镖/投石索/投掷石/料理/金属/宝石/材料/宠物装备等
• 属性: 攻击/防御/敏捷/HP/MP/幸运/魅力/回避/元素
• 堆叠: 可堆叠物品
• 耐久: 物品有损坏和最大损坏度
• 精炼: 精炼系统
• 强化: 物品强化
• 凿孔/镶嵌: 宝石镶嵌系统
• 法宝: 特殊道具系统 6.5 社交系统
• 组队: 最多5人(或8人)组队
• 家族/公会: 1000个家族,100人上限,族长/长老/成员职务,频道系统(5频道)
• 名片/好友: 多页名片册,在线状态显示
• 交易: 双方确认的交易系统,支持物品/宠物/金币
• 邮件: 普通邮件+宠物邮件
• 摆摊: 玩家间交易
• 聊天室: 频道聊天 6.6 多频道系统
• 队伍频道/密语频道/家族频道/职业频道/世界频道/星球频道/聊天室/对话储存 6.7 地图系统
• 格式: Tile-based, 包含 tile/parts/event/hitMap 四层
• 云层效果: 地图云雾效果
• 特殊动画: 环境动画(水中生物/定点动画/随机动画)
• 寻路: 网格式寻路,碰撞检测
• 视野: 按屏幕可见范围渲染
• 天空岛: 特殊地图类型 6.8 家族/庄园系统
• 十大庄园: 庄园争夺战
• 家族PK: 家族间战斗
• 庄园规则: 家族贡献/税收
• 家族徽章: 视觉化家族标识
• 家族频道: 家族内部通信 6.9 扩展系统 (8.0-8.5新增)
• 天使的召唤: 特殊任务系统
• 导师系统: 老玩家带新玩家
• 讨伐魔军: PvE活动系统
• 百人无双: 大型战斗
• 每日活动: 每日任务
• 魔法牌: 卡牌小游戏
• 剧场: 剧情演出功能
• 排行榜: 各类排名NPC
• 签到系统: 每日签到
• 公告系统: 服务器公告
• 商城: 道具商城 6.10 AI/挂机系统
• 自动战斗AI
• 自动遇敌
• 自动喊话 6.11 Lua 脚本系统
• 客户端Lua: 界面定制/窗口管理/标题管理/地图逻辑
• 服务端Lua: NPC逻辑/战斗逻辑/角色操作/物品操作/地图操作/SQL操作
• 使用 LuaJIT 引擎(高性能JIT编译)
• Lua绑定层: 25个绑定模块,覆盖游戏所有系统 6.12 安全系统
• TEA + DES + 个人密钥 加密
• VMProtect SDK 反调试
• MAC 地址验证
• 封包大小检查
• IP 限制和同IP登录限制
• VMP (VMProtect) 保护 七、服务端配置系统 (setup.cf) 关键配置项:
• 网络: 端口19065, fd数1000, 角色数800, 宠物数30000, NPC数45000, 物品数50000, 战斗数500
• 战斗: 战斗速度2000ms, 回合延迟200ms, 经验倍率
• 骑宠: 等级要求140, 转生要求
• 安全: 封包大小检查(登录前300/登录后800), 同IP限制
• 数据: SAAC账号服务端端口10001, MySQL数据库存储
• 活动: 自动PK/六合彩/幸运星等活动配置
• VIP: VIP战斗经验倍率/VIP显示控制

总结: 石器时代8.5是一个功能非常丰富的2D回合制MMORPG,客户端约3万行C++代码,服务端约4-5万行C代码。核心系统包括: 角色/宠物/战斗/物品/魔法/社交/家族/职业等,支持220+条协议通信,77种NPC类型,大量Lua脚本扩展。整个系统从4.0到8.5经历了多次大版本迭代,功能层层叠加。

石器时代客户端重构 — 协议

Context

原版 C++ 有 64 个核心系统、150+ 协议。当前 Cocos 客户端已实现 85 个模块，28 个协议。分 3 批推进。

已完成（不在本计划中）

第一批：P0 — 战斗可玩 + 核心协议（1 周）

B1-1: BattleView 3 个 TODO

目标: 战斗中道具/宠物/技能可用

涉及: BattleView.ts:286/298/310

方案:

• showItemSelect(): 遍历 inventory 中 consumable 物品，生成选择按钮
• showPetSelect(): 从 battle.allyPets 生成选择按钮
• showSkillSelect(): 从 SkillTable 查询宠物可用技能

文件: BattleView.ts

B1-2: GameApp 3 个 TODO

目标: MainMenu skill 按钮连线、帮助/设置内容

方案:

• skill: () => { this.skillView?.toggle(); }
• 帮助/设置: dialogView 显示实际内容

文件: GameApp.ts

B1-3: ProgressBar 组件

目标: StatusView 的 HP/MP/EXP 条用 ProgressBar

方案:

• makeBar() 改为 cc.ProgressBar，保留 Graphics 作为背景轨道

文件: StatusView.ts

B1-4: 协议 58-59 — 宠物技能（PS）

目标: 战斗中使用宠物技能

协议: PS_SEND(havepetindex, havepetskill, toindex, data) → PS_RECV(result, havepetindex, havepetskill, toindex)

方案:

• LssProto.ts: 添加 sendPetSkill() 方法
• GameClient.ts: 添加 petSkill() 方法
• Battle.ts: 扩展 sendPetSkill() 发送协议
• BattleView.ts: showSkillSelect() 连接真实协议

文件: LssProto.ts, GameClient.ts, Battle.ts, BattleView.ts

B1-5: 协议 57 — 魔法使用（MU）

目标: 战斗/地图中使用魔法

协议: MU_SEND(x, y, array, toindex) → 无 recv（结果通过 B/EF 体现）

方案:

• LssProto.ts: 添加 sendMagicUse() 方法
• GameClient.ts: 添加 magicUse() 方法
• Battle.ts: 扩展魔法攻击指令

文件: LssProto.ts, GameClient.ts, Battle.ts

第二批：P1 — 引擎优化 + 经济系统（2 周）

B2-1: tween 缓动系统

目标: 面板打开/关闭动画，按钮点击反馈

方案:

• GameApp.ts 添加 showView()/hideView() 辅助方法
• 全部 34 个 View 的 toggle() 包裹 tween

文件: GameApp.ts + 全部 View

B2-2: ScrollView + Layout 组件

目标: 聊天/道具/宠物列表滚动，装备槽位自动排列

方案:

• ChatView: 消息容器挂载 ScrollView + ScrollBar
• InventoryView: 装备面板改用 Layout VERTICAL
• PetView: 宠物列表改用 Layout
• MainMenu: 菜单项改用 Layout
• BattleView: 命令面板改用 Layout HORIZONTAL

文件: ChatView.ts, InventoryView.ts, PetView.ts, MainMenu.ts, BattleView.ts

B2-3: RichText 聊天格式化

目标: 彩色文字、@提及高亮

方案:

• ChatView refreshMessages() 中 Label 替换为 RichText
• ChatSystem 消息增加格式化信息

文件: ChatView.ts, game/ChatSystem.ts

B2-4: 协议 116-117 — 摆摊系统（Street Vendor）

目标: 玩家间摆摊交易，20 物品栏

协议: STREET_VENDOR_SEND(data) → STREET_VENDOR_RECV(data)

方案:

• 新建 game/StreetVendorSystem.ts — 摊位状态管理
• 新建 cocos/StreetVendorView.ts — 摊位 UI（商品列表 + 价格 + 购买）
• LssProto.ts: 添加摆摊协议 send/recv
• GameClient.ts: 集成摆摊操作
• GameApp.ts: 添加到 UI 管理

文件: 新建 2 + 修改 4

B2-5: 协议 208-209 — 商城系统（Cash Shop）

目标: 彩币购物车，多页商品浏览

协议: SHOPOK_SEND(data) → SHOPOK_RECV(data)

方案:

• 新建 game/CashShopSystem.ts — 商品数据 + 购物车
• 新建 cocos/CashShopView.ts — 商品列表 + 购物车 + 结算
• LssProto.ts: 添加商城协议
• GameClient.ts: 集成商城操作

文件: 新建 2 + 修改 3

B2-6: 协议 107 — 宠物选择确认（PETST）

目标: 服务器确认宠物出场选择

协议: PETST_RECV(petarray, result)

方案:

• LoginFlow.ts: 添加 PETST_RECV 处理器
• GameState.ts: 更新宠物出场状态
• Battle.ts: 同步宠物选择结果

文件: LoginFlow.ts, GameState.ts, Battle.ts

B2-7: 协议 127 — 宠物装备（PET_ITEM_EQUIP）

目标: 宠物穿戴装备

协议: PET_ITEM_EQUIP_SEND(data)

方案:

• LssProto.ts: 添加 sendPetItemEquip() 方法
• PetSystem.ts: 扩展装备槽位管理
• PetView.ts: 添加装备操作 UI

文件: LssProto.ts, PetSystem.ts, PetView.ts

B2-8: 协议 65 — 宠物改名（KN）

目标: 宠物改名

协议: KN_SEND(havepetindex, data)

方案:

• LssProto.ts: 添加 sendPetRename() 方法
• PetView.ts: 添加改名输入框

文件: LssProto.ts, PetView.ts

第三批：P2 — 完整复刻 + 引擎升级（2-3 周）

B3-1: 协议 60-62 — 称号系统（ST/DT/FT）

目标: 设置/删除/查询称号

协议:

• ST_SEND(titleindex) — 设置称号
• DT_SEND(titleindex) — 删除称号
• FT_SEND(data) — 查询称号列表

方案:

• LssProto.ts: 添加 3 个 send 方法
• TitleSystem.ts: 扩展协议交互
• TitleView.ts: 连接真实协议

文件: LssProto.ts, TitleSystem.ts, TitleView.ts

B3-2: 协议 120-121 — 任务日志（JOBDAILY）

目标: 任务日志记录与查询

协议: JOBDAILY_SEND(data) → JOBDAILY_RECV(data)

方案:

• LssProto.ts: 添加任务日志协议
• QuestSystem.ts: 扩展日志记录
• QuestView.ts: 添加日志标签页

文件: LssProto.ts, QuestSystem.ts, QuestView.ts

B3-3: 协议 122-123 — 师徒系统（TEACHER）

目标: 师徒关系管理

协议: TEACHER_SYSTEM_SEND(data) → TEACHER_SYSTEM_RECV(data)

方案:

• 新建 game/TeacherSystem.ts — 关系管理
• 新建 cocos/TeacherView.ts — 师徒 UI
• LssProto.ts: 添加师徒协议

文件: 新建 2 + 修改 2

B3-4: 协议 210-211 — 家族纹章（FAMILYBADGE）

目标: 家族纹章展示

协议: FAMILYBADGE_SEND(data) → FAMILYBADGE_RECV(data)

方案:

• LssProto.ts: 添加纹章协议
• GuildSystem.ts: 扩展纹章数据
• GuildView.ts: 添加纹章展示

文件: LssProto.ts, GuildSystem.ts, GuildView.ts

B3-5: 协议 212-213 — 角色称号（CHARTITLE）

目标: 角色称号显示

协议: CHARTITLE_SEND(data) → CHARTITLE_RECV(data)

方案:

• LssProto.ts: 添加称号协议
• CharacterView.ts: 称号标签展示

文件: LssProto.ts, CharacterView.ts

B3-6: 协议 218-219 — 宠物祝福（VB）

目标: 宠物属性祝福

协议: VB_SEND(data) → VB_RECV(data)

方案:

• LssProto.ts: 添加祝福协议
• PetSystem.ts: 扩展祝福属性
• PetView.ts: 祝福操作 UI

文件: LssProto.ts, PetSystem.ts, PetView.ts

B3-7: 协议 220 — 骑宠查询（RIDEQUERY）

目标: 查询可骑乘宠物

协议: RIDEQUERY_SEND(data)

方案:

• LssProto.ts: 添加查询方法
• RideSystem.ts: 扩展查询逻辑

文件: LssProto.ts, RideSystem.ts

B3-8: 协议 221-222 — 宠物皮肤（PETSKINS）

目标: 宠物皮肤切换

协议: PETSKINS_SEND(data) → PETSKINS_RECV(data)

方案:

• LssProto.ts: 添加皮肤协议
• PetSystem.ts: 扩展皮肤数据
• PetView.ts: 皮肤选择 UI

文件: LssProto.ts, PetSystem.ts, PetView.ts

B3-9: 协议 141 — 签到系统（SIGNDAY）

目标: 月历签到奖励

协议: SIGNDAY_SEND(data)

方案:

• 新建 game/SignInSystem.ts — 签到记录
• 新建 cocos/SignInView.ts — 月历 UI
• LssProto.ts: 添加签到协议

文件: 新建 2 + 修改 1

B3-10: 协议 138 — 百人斩（HUNDREDKILL）

目标: 100 人挑战模式

协议: HUNDREDKILL_RECV(data)

方案:

• LssProto.ts: 添加接收处理
• Battle.ts: 扩展百人斩状态
• BattleView.ts: 百人斩 UI

文件: LssProto.ts, Battle.ts, BattleView.ts

B3-11: 协议 139-140 — PK 列表（PKLIST）

目标: PK 排行榜

协议: PKLIST_SEND(data) → PKLIST_RECV(data)

方案:

• LssProto.ts: 添加 PK 协议
• RankingView.ts: 添加 PK 排行标签

文件: LssProto.ts, RankingView.ts

B3-12: 协议 200 — 公告系统（DENGON）

目标: 服务器公告显示

协议: DENGON_RECV(data)

方案:

• LoginFlow.ts: 添加公告接收处理
• 新建公告显示逻辑（滚动文字或弹窗）

文件: LoginFlow.ts

B3-13: Animation 组件

目标: 角色动作平滑切换

方案:

• CharacterView.ts 用 tween 做 sprite 透明度交叉淡入淡出

文件: CharacterView.ts

B3-14: ParticleSystem2D

目标: 特效升级

方案:

• BattleAnim.ts 伤害数字升级
• WeatherSystem.ts / MapEffects.ts 接入引擎粒子

文件: BattleAnim.ts, WeatherSystem.ts, MapEffects.ts

B3-15: AudioSource

目标: 音频现代化

方案:

• SoundSystem.ts 改用 AudioSource 组件

文件: SoundSystem.ts

协议实现进度

已实现: ████████████████░░░░░░░░░░░░░░ 28/98 (29%)

第一批后: ████████████████████████░░░░░░ 33/98 (34%)
├── +5: PS, MU, PETST, PET_ITEM, KN

第二批后: ██████████████████████████████░ 41/98 (42%)
├── +8: STREET_VENDOR, SHOPOK, + 已有扩展

第三批后: ████████████████████████████████ 56/98 (57%)
├── +15: ST/DT/FT, JOBDAILY, TEACHER, FAMILYBADGE,
│        CHARTITLE, VB, RIDEQUERY, PETSKINS,
│        SIGNDAY, HUNDREDKILL, PKLIST, DENGON

执行顺序

Session 1: P0 — BattleView TODO + GameApp TODO + ProgressBar + PS + MU（1 周）
Session 2: P1-A — tween + ScrollView + Layout + RichText（1 周）
Session 3: P1-B — 摆摊 + 商城 + 宠物选择 + 宠物装备 + 改名（1 周）
Session 4: P2-A — 称号 + 任务日志 + 师徒 + 纹章 + 祝福 + 骑宠查询 + 皮肤（1-2 周）
Session 5: P2-B — 签到 + 百人斩 + PK + 公告 + Animation + Particle + Audio（1 周）

完成度预估

当前:     ████████████████████░░░░░░░░░░ 75%

第一批后: ██████████████████████████░░░░ 85%  ← 可玩 MVP
第二批后: █████████████████████████████░ 95%  ← 功能完整
第三批后: ██████████████████████████████ 100% ← 完整复刻

Context

原版 C++ 客户端有 64 个核心系统，当前 Cocos 客户端已实现 85 个模块（85/86 完成）。核心游戏循环（登录→移动→战斗→升级）已跑通，但缺少 18 个原版系统，协议只实现 ~20%。分 3 批推进。

已完成（不在本计划中）

第一批：P0 — 战斗可玩 + 引擎规范化（1 周）

B1-1: BattleView 3 个 TODO（战斗核心）

目标: 战斗中道具/宠物/技能可用

涉及: BattleView.ts:286/298/310

方案:

• showItemSelect(): 遍历 this.equipSystem.inventory 中的 consumable 物品，生成选择按钮
• showPetSelect(): 从 this.battle.allyPets 生成选择按钮
• showSkillSelect(): 从 SkillTable 查询宠物可用技能

文件: BattleView.ts

B1-2: GameApp 3 个 TODO（一行代码修复）

目标: MainMenu skill 按钮连线、帮助/设置内容

方案:

• skill: () => { this.skillView?.toggle(); }（SkillView 已初始化在 line 727）
• 帮助: this.dialogView.show('帮助', '实际帮助内容...')（加载 DataStore 中的帮助文本）
• 设置: 创建 SettingsView 或接入 dialogView

文件: GameApp.ts

B1-3: ProgressBar 组件 — 替代 Graphics 进度条

目标: StatusView 的 HP/MP/EXP 条用 ProgressBar

方案:

• StatusView 中 makeBar() 方法改为创建 ProgressBar:

  const progressBar = barNode.addComponent(cc.ProgressBar);
  progressBar.barMode = cc.ProgressBar.BarMode.HORIZONTAL;
  progressBar.fillRange = 1;
  // 刷新时: progressBar.progress = hp / maxHp
  

• 保留 Graphics 作为背景轨道，ProgressBar 作为填充层

文件: StatusView.ts

第二批：P1 — 引擎优化 + 核心经济系统（2 周）

B2-1: tween 缓动系统 — UI 面板切换动画

目标: 面板打开/关闭滑入滑出，按钮点击反馈缩放

涉及视图: 全部 34 个面板

方案:

• 所有面板的 toggle() / show() / hide() 方法中，用 cc.tween 替代直接设置 active
• 示例 (InventoryView):

  toggleEquip(): void {
    cc.tween(this.node)
      .to(0.2, { scale: cc.v2(1.05, 1.05) })
      .to(0.1, { scale: cc.v2(1, 1) }, { easing: 'quadOut' })
      .start();
    // ... 现有逻辑
  }
  

• BottomToolbar 按钮的 TOUCH_START/TOUCH_END 用 tween 做缩放反馈

文件: assets/cocos/GameApp.ts + 所有 View

B2-2: ScrollView + Layout 组件 — 长列表滚动 + 自动排列

目标: 聊天/道具/宠物列表支持滚动，装备槽位自动排列

方案:

• ChatView: 消息容器挂载 ScrollView + ScrollBar，inertia 开启
• InventoryView: 道具列表挂载 ScrollView，装备面板改用 Layout VERTICAL
• PetView: 宠物列表改用 Layout + ScrollView
• MainMenu: 菜单项改用 Layout
• BattleView: 命令面板改用 Layout HORIZONTAL

文件: ChatView.ts, InventoryView.ts, PetView.ts, MainMenu.ts, BattleView.ts

B2-3: RichText 组件 — 聊天消息格式化

目标: 聊天消息中显示彩色稀有度文字、@提及高亮

方案:

• ChatView 的 refreshMessages() 中，Label 替换为 RichText
• 构造 RichText 标签字符串: <color=#ff0000>@玩家:</color> 你好

文件: ChatView.ts, game/ChatSystem.ts

B2-4: 商人摆摊系统（Street Vendor）

目标: 玩家间摆摊交易，20 物品栏

原版参考: systeminc/field.h (Show_Sell_Item, Show_Vendor_Item)，20 个物品上限

方案:

• 新建 StreetVendorView.ts — 摊位 UI（商品列表 + 价格 + 购买按钮）
• 新建 game/StreetVendorSystem.ts — 摊位状态管理
• 协议: STREET_VENDOR 系列协议（创建/浏览/购买/关闭）
• 集成到 GameApp.ts + GameClient.ts

文件: 新建 2 个文件 + 修改 3 个文件

B2-5: 商城系统（Cash Shop）

目标: 彩币购物车，多页商品浏览

原版参考: system/shop.cpp — 5 页商品文件，购物车 15 件，MD5 校验

方案:

• 新建 CashShopView.ts — 商品列表 + 购物车 + 结算
• 新建 game/CashShopSystem.ts — 商品数据 + 购物车状态
• 协议: 商品列表请求/购买确认/余额查询

文件: 新建 2 个文件 + 修改 2 个文件

B2-6: 宠物图鉴系统（Pet Album）

目标: 570 种宠物收集册，8 个/页

原版参考: systeminc/menu.h (PET_ALBUM, MAX_PET_KIND=570)

方案:

• 新建 PetAlbumView.ts — 分页网格显示，已收集/未收集状态
• 新建 game/PetAlbumSystem.ts — 收集记录 + 解锁条件
• 复用 DataStore.enemyBase 数据

文件: 新建 2 个文件 + 修改 1 个文件

第三批：P2 — 完整复刻 + 引擎升级（2-3 周）

B3-1: 拍卖行系统（Auction）

目标: NPC 拍卖，出价/一口价/查看

原版参考: systeminc/lssproto_cli.h — EDEN_AUCTION 协议

方案:

• 新建 AuctionView.ts — 拍卖列表 + 出价界面
• 新建 game/AuctionSystem.ts — 拍卖状态管理

B3-2: 签到系统（Sign-In）

目标: 月历签到奖励

原版参考: systeminc/CharSignDay.h — 30 天月历 UI

方案:

• 新建 SignInView.ts — 月历网格 + 领取按钮
• 新建 game/SignInSystem.ts — 签到记录

B3-3: 转盘抽奖系统（Turntable）

目标: 10 格转盘动画 + 奖品

原版参考: systeminc/Turntable.h — 指针旋转 + 速度控制

方案:

• 新建 TurntableView.ts — Canvas 绘制转盘 + tween 旋转动画
• 新建 game/TurntableSystem.ts — 奖品配置 + 结果处理

B3-4: 法宝合成系统（Magic Item）

目标: 3 格合成界面 + 光环效果

原版参考: systeminc/magicitem.h — 3-slot combination

方案:

• 新建 MagicItemView.ts — 合成槽 + 结果预览
• 复用 ItemCrafting.ts 合成逻辑

B3-5: 师徒系统（Teacher）

目标: 师徒关系 + 专属 UI

原版参考: systeminc/lssproto_cli.h — TEACHER_SYSTEM 协议

方案:

• 新建 TeacherView.ts — 师徒列表 + 任务进度
• 新建 game/TeacherSystem.ts — 关系管理

B3-6: 家族进阶功能

目标: 家族纹章 + 庄园挑战 + 家族银行扩展

原版参考: systeminc/pc.h — FAMILYBADGE, MANOR 系统

方案:

• 扩展 GuildView.ts — 纹章展示 + 庄园入口
• 扩展 GuildSystem.ts — 庄园挑战逻辑

B3-7: Animation 组件 — 角色/UI 平滑过渡

目标: 角色动作间平滑切换

方案:

• CharacterView.ts 用 tween 做 sprite 透明度交叉淡入淡出
• 后续如需完整动画系统再引入 Animation Clip

B3-8: ParticleSystem2D — 特效升级

方案:

• BattleAnim.ts 伤害数字升级为 ParticleSystem2D
• WeatherSystem.ts / MapEffects.ts 接入引擎粒子

B3-9: AudioSource — 音频现代化

方案:

• SoundSystem.ts 改用 AudioSource 组件
• 统一 BGM/SFX 管理

关键文件清单

执行顺序与并行度

Session 1: P0 — BattleView TODO + GameApp TODO + ProgressBar（1 周）
  └── 验证: 战斗中道具/宠物/技能可用，进度条正确显示

Session 2: P1-A — tween + ScrollView + Layout + RichText（1 周）
  └── 验证: 面板切换有动画，列表可滚动，聊天彩色文字

Session 3: P1-B — 商人摆摊 + 商城 + 宠物图鉴（1 周，可并行）
  └── 验证: 摆摊交易可用，商城浏览购买，图鉴收集

Session 4: P2-A — 拍卖行 + 签到 + 转盘 + 法宝 + 师徒（1-2 周）
  └── 验证: 各系统独立可用

Session 5: P2-B — 家族进阶 + Animation + Particle + Audio（1 周）
  └── 验证: 引擎组件全部接入

完成度预估

当前: ████████████████████░░░░░░░░░░ 75%

第一批后: ██████████████████████████░░░░ 85%  ← 可玩 MVP
第二批后: █████████████████████████████░ 95%  ← 功能完整
第三批后: ██████████████████████████████ 100% ← 完整复刻

Context

用户需要知道当前 TypeScript 客户端还有多少 Cocos Creator 引擎功能尚未使用。以下对比将引擎提供的 API 与客户端实际实现进行对照。

一、客户端已实现的功能

核心基础设施 (100% 完成)

Cocos 视图 (94% 完成 — 7 个 TODO)

二、引擎有但客户端未使用的功能

1. 音频系统 — 部分使用

引擎提供: AudioSource 组件、AudioClip、AudioManager（中央音频控制器，支持音量/音调控制）

客户端现状: game/SoundSystem.ts 使用原生 HTMLAudioElement，未使用引擎的 AudioSource/AudioManager

差距: 无法使用引擎的音频管理器特性（批量播放、音量混音、音频池）

2. 动画系统 — 完全未使用

引擎提供: Animation 组件、AnimationClip、曲线动画、Animation Graph (Marionette)、CrossFade、CubicSplineValue

客户端现状: 角色动画通过手动切换 sprite frame 实现（CharacterView 中帧索引递增）

差距:

• 无法制作平滑的角色过渡动画（跑动↔待机↔受伤）
• 无法制作 UI 动画（菜单弹出、按钮缩放、面板滑动）
• 无法制作战斗特效动画（伤害数字弹出、状态图标闪烁）
• 无法使用曲线插值（缓入缓出）

3. UI 布局组件 — 完全未使用

引擎提供: Layout（水平/垂直/网格/自适应缩放）、ScrollView、PageView、Toggle/ToggleContainer、Slider、ProgressBar、EditBox、RichText、Button（4 态转换）

客户端现状: 所有 UI 手动定位 + 手动拖拽（DragHelper）。InventoryView/PetView 等面板没有使用 Layout 或 ScrollView。

差距:

• 道具列表、宠物列表、聊天消息等长列表无法滚动
• 装备槽位无法自动排列（Layout 可自动处理）
• 等级进度条、经验条等手动用 Graphics 绘制，应改用 ProgressBar 组件
• 聊天输入框手动实现，应使用 EditBox
• 技能/职业树展示无法自动排列

4. 粒子系统 — 部分使用

引擎提供: ParticleSystem2D（2D 粒子）、ParticleSystem（3D 粒子）、MotionStreak（拖尾效果）

客户端现状: game/WeatherSystem.ts 和 game/MapEffects.ts 标记了"粒子天气"和"粒子地图效果"，但实际实现需查看具体代码。game/WarpEffect.ts 有转场动画效果。

差距:

• 战斗伤害数字/治疗数字目前可能是手动 DOM 动画，可用 ParticleSystem2D 做华丽效果
• 角色移动轨迹、技能释放效果可用 MotionStreak
• 天气效果（雨/雪/雾）可用引擎粒子系统

5. 物理系统 — 完全未使用

引擎提供: RigidBody2D、BoxCollider2D、CircleCollider2D、PolygonCollider2D、9 种 Joint（Hinge/Distance/Spring/Mouse/Slider/Fixed/Relative/Wheel）

客户端现状: 碰撞检测完全手动（GroundItemRenderer.hitTest、坐标距离判断）

差距: 对 2D 等距 RPG 游戏来说物理引擎非必需，碰撞检测手动实现足够。此项可以跳过。

6. 资源加载系统 — 部分使用

引擎提供: Bundle 系统、resources.load()、依赖管理、资源池、预加载/释放

客户端现状: 手动 fetchBinary() + 自定义 SpriteStore 缓存。已实现 Range 请求优化。

差距: 引擎的资源管线（下载→解析→缓存→释放）更完善，但客户端的自定义方案已能工作。此项可跳过。

7. Shader/Material — 完全未使用

引擎提供: Material、Pass、ProgramLibrary、RenderPipeline、ToneMapping

客户端现状: 无自定义 shader，纯 sprite rendering

差距: 如需高级视觉效果（屏幕特效、角色发光、水面波纹）需使用，但当前阶段非必需。可跳过。

8. 视频播放 — 未使用

引擎提供: VideoPlayer 组件、VideoClip

客户端现状: 无视频功能

差距: 如有过场动画/宣传片需求才需要。非必需。

9. WebView — 未使用

引擎提供: WebView 组件

客户端现状: 无 WebView

差距: 如有用户协议/客服/外部链接内嵌才需要。非必需。

10. 骨骼动画 — 完全未使用

引擎提供: Skeleton 组件（Spine 运行时）、ArmatureDisplay（DragonBones）

客户端现状: 所有角色/敌人用静态 sprite frame + 帧索引动画

差距: 引擎已内置 Spine/DragonBones 支持。如果后续美术资源升级为骨骼动画（平滑动作），可以直接使用。长期有价值，当前可跳过。

11. 输入系统 — 部分使用

引擎提供: Input 组件、SystemEvent（触摸/键盘/鼠标/手柄抽象）

客户端现状: 使用 cc.systemEvent（SystemEvent）处理键盘，手动监听 touch/mouse 事件

差距: 引擎的 Input 系统提供了按键映射、多触控追踪等能力。客户端的手动实现基本等价，但无法利用引擎的按键绑定系统。可跳过或逐步迁移。

12. tween/缓动系统 — 完全未使用

引擎提供: tween API（.to/.by/.set/.call/.delay）、48 种缓动函数（quad/cubic/quint/sine/expo/circ/elastic/bounce）

客户端现状: 无缓动动画，UI 切换全部瞬间完成

差距:

• 面板打开/关闭的滑入滑出动画
• 按钮点击反馈动画
• 伤害数字弹跳动画
• 角色移动插值

13. 富文本 — 未使用

引擎提供: RichText 组件（HTML-like 标签格式化文本）

客户端现状: 聊天消息使用纯文本 Label

差距: 聊天中@提及高亮、彩色稀有度文字、链接点击等需要用 RichText。值得实现。

14. 调试工具 — 部分使用

引擎提供: Profiler 组件（帧率/渲染计数器）、debug-view

客户端现状: 大量 console.log 调试，无引擎 Profiler

差距: 可启用引擎 Profiler 监控性能。当前阶段可跳过。

15. 安全区域 — 未使用

引擎提供: SafeArea 组件

客户端现状: 手动计算（通过 cc.view.getSafeAreaRect()）

差距: 引擎的 SafeArea 组件可以直接挂在节点上自动收缩到安全区域内，比手动计算更安全。建议实现。

16. TMX/Tiled 地图 — 未使用

引擎提供: TiledMap、TiledLayer、TiledObjectGroup

客户端现状: 自定义 .dat 格式地图

差距: 引擎已支持标准 Tiled 编辑器格式，但当前自定义格式已能工作。如后续改用 Tiled 编辑器可考虑。

三、差距优先级排序

P0 — 立即需要（直接影响玩家体验）

1. tween 缓动系统 — UI 面板切换、按钮交互、战斗特效需要动画
2. Layout 组件 — 列表类 UI（道具/宠物/技能）需要自动排列
3. ScrollView 组件 — 聊天消息、道具列表需要滚动
4. RichText 组件 — 聊天消息格式化（稀有度颜色、@提及高亮）
5. SafeArea 组件 — 灵动岛/刘海遮挡问题

P1 — 近期需要

6. Animation 组件 — 角色待机/跑动平滑过渡，UI 动效
7. ProgressBar 组件 — HP/MP/经验条用 ProgressBar 替代 Graphics
8. EditBox 组件 — 聊天输入框、好友搜索等

P2 — 长期优化

9. ParticleSystem2D — 战斗特效、天气效果
10. Spine/DragonBones — 骨骼动画（美术升级时）
11. AudioSource/AudioManager — 音频管理现代化

P3 — 非必需

12. 物理系统 — 2D RPG 不需要
13. VideoPlayer/WebView — 视需求添加
14. TMX/Tiled — 已有自定义格式工作正常
15. Shader/Material — 后期优化时考虑
16. Profiler — 性能分析用

四、关键文件对照

分支: claude-session-b/skill-pet-system 负责范围: Phase 2 技能系统 + Phase 4 宠物系统完善

Phase 2: 技能系统（P0）

2.1 玩家技能UI

文件: 新建 assets/cocos/SkillView.ts, 修改 assets/cocos/GameApp.ts

2.1.1 技能列表窗口

• 新建 SkillView.ts — 技能查看/学习窗口
• 窗口结构: 标题栏(可拖拽) + 分隔线 + 技能列表 + 技能详情
• 已学技能列表: 显示名称、等级、描述、当前效果
• 可学习技能列表: 在NPC处显示可学习的技能
• 技能升级按钮: 发送 sendSkillUpgrade(ws, skillId) 协议
• 参考现有 View 模式（InventoryView/PetView 的风格）

数据结构参考 (assets/game/ProfessionSystem.ts 已有):

interface Skill {
  id: number;
  name: string;
  level: number;
  maxLevel: number;
  description: string;
  effect: string;
  cost: number;  // 学习/升级消耗
}

2.1.2 技能快捷键栏

• 在 BottomToolbar.ts 中添加技能快捷键区域
• 支持配置最多4个技能快捷键
• 战斗中点击快捷键直接使用技能

2.2 宠物技能UI

文件: 新建 assets/cocos/PetSkillView.ts, 修改 assets/cocos/PetView.ts

2.2.1 宠物技能列表

• 新建 PetSkillView.ts — 宠物技能查看窗口
• 在 PetView 的宠物详情页添加"技能"按钮
• 技能列表: 显示每个技能的名称、类型、描述、威力
• 技能类型分类: 攻击型/防御型/特殊型

原版宠物技能类型参考 (stoneage/client-8.5/.../pet_skillinfo.h):

PETSKILL_NORMALATTACK(1)  PETSKILL_NORMALGUARD(2)   PETSKILL_GUARDBREAK(3)
PETSKILL_CONTINUATIONATTACK(10-13)  PETSKILL_GUARDIAN(20)  PETSKILL_CHARGE(30-31)
PETSKILL_MIGHTY(40-41)  PETSKILL_POWERBALANCE(50-52)  PETSKILL_POISON_ATTACK(60-61)
PETSKILL_STONE(80)  PETSKILL_CONFUSION_ATTACK(90)  PETSKILL_DRUNK_ATTACK(100)
PETSKILL_SLEEP_ATTACK(110)  PETSKILL_EARTHROUND(120)  PETSKILL_Abduct(130)
PETSKILL_STEAL(140)  PETSKILL_NOGUARD(150-152)  PETSKILL_MERGE(200-201)
PETSKILL_ALCHEMIST(202)  PETSKILL_INSLAY(572)  PETSKILL_FIXITEM(540/664)
PETSKILL_INTENSIFY(650)  PETSKILL_UPINSLAY(651)  PETSKILL_CALLBUS(668)

2.2.2 宠物技能学习

• 在NPC处学习宠物技能的交互窗口
• 技能遗忘确认对话框
• 发送对应 WN 协议响应

Phase 4: 宠物系统完善（P1）

4.1 宠物完整操作

文件: assets/cocos/PetView.ts

4.1.1 宠物改名

• 在宠物详情页添加"改名"按钮
• 弹出输入框（使用 Cocos Label + 键盘输入处理）
• 发送 KN 协议: old_lssproto_KN_send(fd, havepetindex, data)
• 更新宠物显示名称

4.1.2 宠物属性加点

• 升级后显示可分配属性点数量
• 加点面板: HP / 攻击 / 防御 / 敏捷 四个选项
• 每个属性显示当前值和可加点数
• 发送对应协议分配属性点

4.1.3 宠物合成

• 新建宠物合成选择窗口
• 选择两只宠物进行合成
• 显示合成结果预览（可能的后代属性范围）
• 确认合成按钮

4.2 骑乘系统

文件: 新建 assets/cocos/RideView.ts（RideSystem.ts 已有数据层）

4.2.1 骑乘按钮

• 新建 RideView.ts — 骑乘状态管理
• 在 BottomToolbar 或 StatusView 中添加骑乘按钮
• 显示当前骑乘状态（骑乘中/下马状态）
• 切换骑乘/下马状态
• 骑乘时角色外观变化（使用 RideSystem 中的数据）
• 发送对应协议切换状态

技术规范

1. Layer: 所有 new cc.Node() 创建的子节点必须 node.layer = 1 << 25
2. UITransform: 所有 UI 子节点必须 addComponent(UITransform)
3. 拖拽: 所有弹窗窗口添加 titleBar + makeDraggable()
4. 代码风格: 遵循 COCOS_STYLE_GUIDE.md — 动态创建UI节点，不使用预制体
5. 无注释: 命名即文档，只在非显而易见处写注释

依赖关系

• Phase 2.1 需要 GameApp.ts 中注册 SkillView（需要 session-a 先完成 BottomToolbar 修改）
• Phase 4.1 依赖 PetView.ts 的基础结构（已存在）
• 与 session-a 无直接代码冲突，可并行开发

Commit 格式

[session-b] feat: 简短描述

Phase 1: 战斗系统完善（P0）

1.1 完整战斗指令UI

文件: assets/cocos/BattleView.ts, assets/game/Battle.ts, assets/net/ProtocolParser.ts

1.1.1 战斗指令面板重构

• 将现有3个按钮（攻击/防御/逃跑）扩展为6个：攻击、防御、道具、宠物、技能、逃跑
• 点击"攻击"后弹出敌方目标选择面板（列出所有敌方角色，带HP信息）
• 点击"道具"后弹出背包道具选择面板（显示可用道具列表）
• 点击"宠物"后弹出宠物选择面板（显示我方宠物列表，可切换出战宠物）
• 点击"技能"后弹出宠物技能选择面板（显示当前宠物的技能列表）
• 每个子面板需要有"返回"按钮回到主指令面板

协议发送:

• 攻击: BattleAction.ATTACK|targetBid|0|0|
• 防御: BattleAction.DEFEND|0|0|0|
• 道具: BattleAction.ITEM|targetBid|0|itemSlot|
• 宠物: BattleAction.PET_ATTACK|targetBid|skillId|0|
• 技能: BattleAction.SKILL|targetBid|skillId|0|
• 逃跑: BattleAction.ESCAPE|0|0|0|

1.1.2 战斗角色展示

• 敌方角色区域（右上）: 显示每个敌人的名称、等级、HP条
• 我方角色区域（左下）: 显示玩家名称、HP/MP条 + 出战宠物名称、HP条
• HP条使用不同颜色: HP满=绿色, HP低=红色
• 角色死亡时显示灰色/删除线标记

1.1.3 战斗日志完善

• 多行滚动日志（最多20行，显示最近8行）
• 不同颜色区分消息类型:
  • 普通消息: 白色
  • 伤害: 红色
  • 治疗: 绿色
  • 状态变化: 紫色
  • 系统提示: 黄色
• 回合开始时显示 --- 第 N 回合 ---

1.1.4 战斗协议完善

• ProtocolParser.ts 中完善 parseBattleCommand 的 BC/BP/BA/BU 解析
• Battle.ts 中增加 sendItem, sendPetSwitch, sendPetSkill 方法
• 处理战斗中的 HP 实时更新（从 BA 协议解析）

1.2 战斗动画与特效

文件: 新建 assets/cocos/BattleAnim.ts, 修改 BattleView.ts

1.2.1 伤害数字弹出

• 创建 floating text 动画节点
• 攻击命中时在被攻击者位置弹出红色伤害数字
• 治疗时弹出绿色治疗数字
• MISS 时弹出灰色 "MISS" 文字

1.2.2 状态效果显示

• 中毒/睡眠/混乱/眩晕 状态图标显示在角色旁边
• 状态生效/解除时在日志中显示对应颜色的文字

Phase 3: 物品交互完善（P1）

3.1 地面物品拾取/丢弃

文件: assets/cocos/MapRenderer.ts, assets/cocos/InputController.ts, assets/cocos/GameApp.ts

3.1.1 地面物品渲染

• 在 GameApp.ts 中处理 CA 协议返回的 ItemObjData 和 GoldObjData
• 在地图上绘制物品图标（使用 adrnIndex 中的 sprite）
• 物品名称悬浮提示（鼠标悬停/触摸时显示）
• 金币用特殊图标显示

3.1.2 拾取交互

• 点击地面物品弹出拾取确认窗口
• 发送 PI 协议拾取: sendPickItem(ws, x, y, dir)
• 发送 DI 协议丢弃: sendDropItem(ws, x, y, itemIndex)
• 发送 DG 协议丢弃金币: 需要新建 sendDropGold 函数

3.2 物品详情

文件: assets/cocos/InventoryView.ts

3.2.1 物品属性面板

• 点击背包中的物品弹出详情面板
• 显示: 名称、类型、等级、耐久度、属性、描述
• 操作按钮: 使用（消耗品）/ 装备（装备品）/ 丢弃
• 装备后更新 EquipmentSystem 状态

3.2.2 物品堆叠

• 同类物品合并显示（名称+数量）
• 拆分堆叠功能（输入拆分数量）

3.3 银行/仓库

文件: 新建 assets/cocos/BankView.ts（ItemBank.ts 已有数据层）

• 银行窗口UI（标题栏可拖拽）
• 左侧: 银行存款列表
• 右侧: 背包物品列表（可双击存入）
• 存款/取款按钮
• 与 GameClient 连接发送对应协议

技术规范

1. Layer: 所有 new cc.Node() 创建的子节点必须 node.layer = 1 << 25
2. UITransform: 所有 UI 子节点必须 addComponent(UITransform)
3. 拖拽: 所有弹窗窗口添加 titleBar + makeDraggable()
4. 协议: 保持 | 分隔字段格式
5. 无注释: 命名即文档，只在非显而易见处写注释

Commit 格式

[session-a] feat: 简短描述

全局状态

分支与 Worktree 设置

三个 session 现在各自拥有独立的 worktree 目录：

⚠️ 注意: 三个分支目前指向同一个 commit (b5459ae)。后续各自提交的代码会逐步分离。

如何同步代码

当 session-a 提交了新代码后，session-b/c 可以通过以下方式同步：

# 在 session-b 或 session-c 的 worktree 目录下
git fetch origin
git merge origin/claude-session-a/battle-skill-item-pet-system

合并时如果有冲突，用 --ours / --theirs 解决即可。

Session-A 已完成

Phase 1: 核心战斗系统 ✅

新增文件:

• assets/cocos/BattleView.ts — 完整战斗UI（攻击/防御/道具/宠物/技能/逃跑）
• assets/cocos/BattleCharaRenderer.ts — 战斗角色渲染（HP条/状态标记）

修改文件:

• assets/net/LssProto.ts — 新增 BU_RECV(15) 协议、sendUseItem/sendPetTurn/sendPetSkill
• assets/net/ProtocolParser.ts — 完善 BC/BP/BU 协议解析
• assets/game/Battle.ts — 完善战斗状态机、解析服务端战斗数据
• assets/cocos/GameApp.ts — 集成 BattleView、B键切换战斗面板

Phase 3: 物品交互系统 ✅

新增文件:

• assets/cocos/GroundItemRenderer.ts — 地面物品渲染（CA协议解析后的ItemObjData/GoldObjData可视化）
• assets/cocos/GroundItemPickupView.ts — 地面物品拾取/丢弃确认弹窗
• assets/cocos/BankView.ts — 银行/仓库窗口（个人+家族仓库，金币存取）

修改文件:

• assets/cocos/InventoryView.ts — 添加物品详情面板、使用/装备/丢弃/拆分按钮
• assets/cocos/InputController.ts — 添加 getGroundItemHit 回调，点击地面物品检测
• assets/cocos/GameApp.ts — 集成地面物品点击/拾取/丢弃逻辑、N键打开银行
• assets/net/LssProto.ts — 新增 DG_RECV(20) 协议、sendDropGold

Session-B 待完成

Phase 2: 技能系统

目标文件:

• assets/cocos/SkillView.ts — 已有骨架，需完善玩家技能列表/升级UI
• assets/cocos/PetSkillView.ts — 新建，宠物技能查看/学习
• assets/cocos/PetView.ts — 添加"技能"标签页入口
• assets/game/SkillSystem.ts — 已有数据层，确认技能定义完整性
• assets/net/LssProto.ts — 确认 SK(技能升级) 协议实现

功能清单:

• 技能列表窗口（已学技能 + 可学习技能）
• 技能升级按钮 + 确认
• 宠物技能列表（40+种技能类型）
• 技能描述面板
• 战斗中技能快捷选择

Phase 4: 宠物系统完善

目标文件:

• assets/cocos/PetView.ts — 添加改名/属性加点/合成功能
• assets/cocos/RideView.ts — 已有骨架，需完善骑乘UI
• assets/game/PetSystem.ts — 确认属性加点数据结构
• assets/net/LssProto.ts — 确认 KN(改名)/宠物合成 协议

功能清单:

• 宠物改名（输入新名称 → KN协议）
• 宠物属性加点（HP/攻击/防御/敏捷）
• 宠物合成（选两只宠物 → 合成结果预览）
• 骑乘/下马切换按钮

Session-C 待完成

Phase 5: 社交系统

目标文件:

• assets/cocos/PartyView.ts — 已有骨架，需完善组队UI
• assets/cocos/FriendView.ts — 已有骨架，需完善好友UI
• assets/cocos/PlayerPopupMenu.ts — 已有骨架，玩家右键菜单
• assets/cocos/TradingView.ts — 完善双边交易流程
• assets/game/PartySystem.ts / assets/game/FriendSystem.ts / assets/game/Trading.ts — 确认数据层

功能清单:

• 组队邀请/确认/退出
• 队员列表/HP状态/队长标记
• 好友添加/删除/在线状态
• 私聊窗口（双击好友打开）
• 交易物品选择 + 金币设置
• 双方确认流程（锁定→确认→执行）

Phase 6: 地图与世界交互

目标文件:

• assets/cocos/DialogView.ts — 完善NPC对话
• assets/cocos/NpcWindow.ts — 已有，解析WN协议动态窗口
• assets/cocos/InputController.ts — 添加点击其他玩家检测
• assets/cocos/CharacterView.ts — 玩家信息展示
• assets/cocos/BottomToolbar.ts — 已有骨架，底部快捷栏

功能清单:

• WN协议窗口解析（按钮/列表/输入框/多页）
• 靠近NPC按交互键触发对话
• 地图切换/传送点处理
• 点击其他玩家弹出信息面板（名称/等级/称号/家族）
• 玩家交互菜单（组队/交易/私聊）

Phase 7: 界面与系统功能（未分配）

• MainMenu.ts — 主菜单（人物/道具/宠物/任务/家族/技能/帮助/设置）
• TitleView.ts — 称号查看/切换
• RankingView.ts — 排行榜
• DragHelper.ts — 窗口位置持久化（localStorage）
• SettingsView.ts — 系统设置（音效/画质/屏蔽）

文件归属参考

各 session 负责的文件范围，避免冲突：

备注

• 所有新文件已提交到 claude-session-a/battle-skill-item-pet-system 分支
• session-b 和 session-c 的 worktree 目录下已有各自的代码骨架（SkillView/BankView/PartyView 等），但那些文件是在主工作目录创建的，需要通过 git checkout 或手动复制到对应 worktree
• 建议各 session 在开始工作前，先 git merge session-a 的最新提交，确保基础功能完整

📦 镜像管理

🚀 容器生命周期

🏃 docker run 常用参数

docker run \
  -d                          \  # 后台运行
  --name <名称>                \  # 容器命名
  -p <宿主端口>:<容器端口>      \  # 端口映射
  -v <宿主路径>:<容器路径>      \  # 目录挂载
  -e <变量名>=<值>             \  # 环境变量
  --network <网络名>           \  # 指定网络
  --restart unless-stopped     \  # 自动重启策略
  --rm                         \  # 停止后自动删除
  -it <镜像> /bin/bash            # 交互式进入
  <镜像名>:<标签>

restart 策略

📋 容器查看

🔍 容器详情（inspect）

💾 数据卷（Volume）

-v vs --mount

# -v 简写
docker run -v /host/path:/container/path <镜像>

# --mount 更明确
docker run --mount type=bind,source=/host/path,target=/container/path <镜像>
docker run --mount type=volume,source=myvol,target=/container/path <镜像>

🌐 网络管理

🐙 Docker Compose

docker-compose.yml 模板

version: "3.8"
services:
  app:
    image: nginx:latest
    container_name: my-app
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./data:/var/lib/data
      - app_config:/etc/config
    environment:
      - DB_HOST=db
      - DB_PORT=5432
    depends_on:
      - db
    restart: unless-stopped
    networks:
      - frontend

  db:
    image: postgres:15
    container_name: my-db
    volumes:
      - db_data:/var/lib/postgresql/data
    environment:
      - POSTGRES_PASSWORD=secret
    restart: unless-stopped
    networks:
      - frontend

volumes:
  app_config:
  db_data:

networks:
  frontend:

🧹 清理命令

🔧 实用技巧

进入运行中的容器

docker exec -it <容器> /bin/bash
# 如果没有 bash：
docker exec -it <容器> /bin/sh

容器间文件拷贝

# 容器 → 宿主机
docker cp <容器>:<容器路径> <宿主路径>

# 宿主机 → 容器
docker cp <宿主路径> <容器>:<容器路径>

查看容器资源占用

docker stats --no-stream  # 一次性输出，不持续刷新

导出/导入容器

docker export <容器> -o <文件名>.tar   # 导出容器为 tar
docker import <文件名>.tar <新镜像名>   # 导入为镜像

重命名容器

docker rename <旧名> <新名>

查看容器运行时的完整命令

docker ps --no-trunc --format "{{.Names}}: {{.Command}}"

⚡ 一行命令集合

# 删除所有已停止的容器
docker rm $(docker ps -aq --filter status=exited)

# 删除所有镜像
docker rmi $(docker images -q)

# 停止所有运行中的容器
docker stop $(docker ps -q)

# 删除所有容器（含运行中）
docker rm -f $(docker ps -aq)

# 查看所有容器 IP
docker inspect -f '{{.Name}} - {{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' $(docker ps -aq)

# 按大小排序镜像
docker images --format "{{.Repository}}:{{.Tag}} {{.Size}}" | sort -k2 -h

路由器环境

360 T7 搭载联发科 MT7981 (Filogic 820) 芯片，双核 Cortex-A53 aarch64，230MB 内存，Flash 只有 63MB 左右。刷的是 ImmortalWrt 24.10-SNAPSHOT。

原始 ipk 包的问题

从官方下载的 luci-app-fcclient_3.0.7-202605210720_all.ipk 有 25MB，解压后 data 区 53MB，其中：

• 5 个架构的二进制文件（netflow_mips / mipsel / arm / x86_64 / aarch64），加起来接近 10MB
• geo 数据库（geoip.dat + geosite.dat + GeoLite2-ASN.mmdb + geoip.metadb）约 43MB

而 360 T7 只认 aarch64，其他 4 个架构纯属浪费空间。

精简过程

写了一个 shell 脚本 trim_ipk.sh，逻辑很简单：把 ipk 解压后删掉不需要的架构二进制，只保留 netflow_aarch64，再重新打包。

结果从 25MB 砍到 1.9MB，精简效果立竿见影。不过这也只是二进制部分，geo 数据库不在这个包里。

安装后的两个坑

坑一：二进制名不匹配

安装后服务死活启动不了，/etc/init.d/netflow status 显示 "active with no instances"。查了一下 init 脚本，发现它找的是 /usr/bin/netflow，但 ipk 里安装的文件叫 netflow_aarch64。

手动创建一个软链接解决：

ln -sf /usr/bin/netflow_aarch64 /usr/bin/netflow

坑二：geo 数据库丢失

精简包只管二进制，geo 数据库需要单独安装。从本地解压 geodata_mihomo.tar.gz 上传到路由器，放到 /etc/netflow/mihomo/ 目录下。注意解压时 tar 会自动多创建一层 etc/ 目录，需要手动整理文件结构。

4 个数据库文件加起来约 43MB，解压后目录结构应该是：

/etc/netflow/mihomo/
├── geoip.dat          (18.3 MB)
├── geoip.metadb       (8.8 MB)
├── geosite.dat        (4.0 MB)
└── GeoLite2-ASN.mmdb  (11.6 MB)

最后

创建好软链接、放好数据库、重启服务，/etc/init.d/netflow start 后状态变为 "running"。

整个过程最大的感受是，OpenWrt 上有些包不是独立封装的，安装时最好检查一下 control 文件里的依赖关系和安装后的文件列表，避免装完发现缺东少西。另外路由器 Flash 和内存都紧张，精简包是刚需，特别是这种多架构合一的 ipk，删掉不用的架构能省不少空间。