本文记录项目初始化的完整过程：技术选型、架构设计、核心实现和 API 测试。

一、技术选型：Python + DeepSeek

1.1 编程语言选择

考虑过 Go、Rust，但最终选择 Python：

优势明显：

• AI 生态最成熟（OpenAI SDK、Anthropic SDK 都是 Python 优先）
• 开发速度快（1-2 周就能做出 MVP）
• 标准库强大（文件操作、正则、subprocess 开箱即用）
• 打包方案成熟（PyInstaller / Nuitka）

权衡成本：

• 打包体积大（20-40MB）
• 启动速度慢（1-2秒）

对于 MVP 阶段，开发效率优先于运行效率。

1.2 LLM 提供商：DeepSeek 起步

价格对比（修复 100 个 Bug 的实际成本）：

作为个人开发者，DeepSeek 的性价比无敌 —— 比 Claude 便宜 300 倍！

架构设计支持未来扩展：

• 智谱 GLM（备选方案）
• Anthropic Claude（高端场景）
• OpenAI GPT（兼容性考虑）

1.3 界面：CLI 优先

选择命令行界面而不是 GUI：

• ✅ 简单高效，开发成本低
• ✅ 适合开发者使用场景
• ✅ 易于自动化和集成

二、架构设计：多模型抽象层

2.1 核心循环

Agent 的本质是一个反馈循环：

用户输入任务
  ↓
┌─────────────────┐
│  查询 LLM       │
└────────┬────────┘
         ↓
┌─────────────────┐
│  解析 Action    │ → bash / read_file / write_file / exit
└────────┬────────┘
         ↓
┌─────────────────┐
│  执行 Action    │
└────────┬────────┘
         ↓
┌─────────────────┐
│  反馈结果       │
└────────┬────────┘
         │
         └─→ 循环，直到完成或超时

2.2 多模型架构：抽象工厂模式

使用抽象基类 + 工厂函数实现多模型支持：

# models/base.py - 抽象基类
class BaseLLMProvider(ABC):
    @abstractmethod
    def query(self, messages: List[Dict]) -> str:
        """查询模型"""
        pass
    
    @abstractmethod
    def get_model_info(self) -> Dict:
        """获取模型信息（名称、价格、上下文长度）"""
        pass

# models/deepseek.py - DeepSeek 实现
class DeepSeekProvider(BaseLLMProvider):
    def __init__(self, api_key: str, model: str, base_url: str):
        self.client = OpenAI(
            api_key=api_key,
            base_url=base_url  # 硅基流动: https://api.siliconflow.cn/v1
        )
        self.model = model
    
    def query(self, messages: List[Dict]) -> str:
        response = self.client.chat.completions.create(
            model=self.model,
            messages=messages
        )
        return response.choices[0].message.content

# models/factory.py - 工厂函数
PROVIDERS = {
    "deepseek": DeepSeekProvider,
    "zhipu": ZhipuProvider,      # 未来支持
    "anthropic": AnthropicProvider,  # 未来支持
}

def create_provider(provider_name: str, api_key: str, **kwargs):
    return PROVIDERS[provider_name](api_key, **kwargs)

好处：

• 新增模型只需实现 3 个方法
• 切换模型只需修改配置
• 统一接口，代码清晰

2.3 Action 解析器

从 LLM 输出中提取结构化命令：

# utils/parser.py
class ActionParser:
    @staticmethod
    def parse_bash_action(text: str) -> Optional[str]:
        """解析 bash 命令：```bash-action\n<command>\n```"""
        matches = re.findall(
            r"```bash-action\s*\n(.*?)\n```",
            text,
            re.DOTALL
        )
        return matches[0].strip() if matches else None
    
    @staticmethod
    def parse_read_file(text: str) -> Optional[str]:
        """解析读取文件：```read-file\n<filepath>\n```"""
        matches = re.findall(
            r"```read-file\s*\n(.*?)\n```",
            text,
            re.DOTALL
        )
        return matches[0].strip() if matches else None
    
    @staticmethod
    def parse_write_file(text: str) -> Optional[Dict]:
        """解析写入文件：```write-file\n<filepath>\n---\n<content>\n```"""
        matches = re.findall(
            r"```write-file\s*\n(.*?)\n---\n(.*?)\n```",
            text,
            re.DOTALL
        )
        if matches:
            filepath, content = matches[0]
            return {"path": filepath.strip(), "content": content}
        return None

支持多种 Action 类型：

• bash-action - 执行 shell 命令
• read-file - 读取文件
• write-file - 写入文件
• exit - 完成任务

2.4 工具系统

命令执行器（tools/execute.py）：

class CommandExecutor:
    def execute(self, command: str) -> Dict:
        result = subprocess.run(
            command,
            shell=True,
            text=True,
            stdout=subprocess.PIPE,
            stderr=subprocess.PIPE,
            timeout=30,
            env=self.env  # 禁用交互式工具
        )
        return {
            "stdout": result.stdout,
            "stderr": result.stderr,
            "returncode": result.returncode,
            "success": result.returncode == 0
        }

文件操作（tools/file_ops.py）：

class FileOperations:
    @staticmethod
    def read_file(filepath: str) -> str:
        """读取文件，带行号"""
        with open(filepath, 'r', encoding='utf-8') as f:
            content = f.read()
        lines = content.split('\n')
        numbered = '\n'.join([f"{i+1:4d} | {line}" for i, line in enumerate(lines)])
        return f"📄 {filepath}\n{numbered}"
    
    @staticmethod
    def write_file(filepath: str, content: str) -> str:
        """写入文件，自动创建目录"""
        directory = os.path.dirname(filepath)
        if directory and not os.path.exists(directory):
            os.makedirs(directory)
        with open(filepath, 'w', encoding='utf-8') as f:
            f.write(content)
        return f"✅ 已写入 {filepath}"

三、核心实现：300 行代码的 Agent

3.1 主循环

# agent.py
class MeowCodeAgent:
    def run(self, user_task: str):
        # 初始化对话
        self.messages = [
            {"role": "system", "content": self.system_prompt},
            {"role": "user", "content": user_task}
        ]
        
        for iteration in range(self.max_iterations):
            # 1. 查询 LLM
            lm_output = self.provider.query(self.messages)
            self.messages.append({"role": "assistant", "content": lm_output})
            
            # 2. 解析 action
            action = self.parser.parse_action(lm_output)
            if not action:
                continue
            
            if action["type"] == "exit":
                break
            
            # 3. 执行 action
            result = self.execute_action(action)
            
            # 4. 反馈结果
            self.messages.append({"role": "user", "content": result})

3.2 配置系统

使用 YAML + 环境变量：

# config/config.yaml
llm:
  provider: deepseek
  deepseek:
    api_key: ""  # 或从环境变量 DEEPSEEK_API_KEY 读取
    model: deepseek-ai/DeepSeek-V3.2
    base_url: https://api.siliconflow.cn/v1

agent:
  system_prompt: |
    You are a helpful coding assistant.
    When you want to run a command, wrap it in ```bash-action
    <command>
    ```
  max_iterations: 20
  command_timeout: 30

配置加载器自动合并环境变量：

class Config:
    def get_llm_config(self) -> Dict:
        provider = self.get('llm.provider', 'deepseek')
        provider_config = self.get(f'llm.{provider}', {})
        
        # 优先从环境变量读取 API Key
        env_key = f"{provider.upper()}_API_KEY"
        if env_key in os.environ:
            provider_config['api_key'] = os.environ[env_key]
        
        return {"provider": provider, **provider_config}

四、测试与验证

4.1 API 连接测试

硅基流动配置：

• Base URL: https://api.siliconflow.cn/v1
• 模型: deepseek-ai/DeepSeek-V3.2
• 兼容 OpenAI SDK

测试代码：

from openai import OpenAI

client = OpenAI(
    api_key="sk-xxx",
    base_url="https://api.siliconflow.cn/v1"
)

response = client.chat.completions.create(
    model="deepseek-ai/DeepSeek-V3.2",
    messages=[
        {"role": "system", "content": "你是一个有帮助的助手。"},
        {"role": "user", "content": "你好，请用一句话介绍你自己。"}
    ]
)

测试结果：

• ✅ API 调用成功
• ✅ 响应速度快（<2秒）
• ✅ Token 使用：36 tokens（输入 18 + 输出 18）

4.2 Action 解析测试

任务：”列出当前目录的文件”

LLM 响应：

\```bash-action
ls
\```

解析结果：

• ✅ 类型：bash
• ✅ 数据：ls

4.3 完整流程测试

测试场景：列出当前目录文件并生成总结

执行流程：

1. 用户输入：”列出当前目录的文件”

2. Agent 第 1 轮：
   • 生成命令：ls -la
   • 执行并返回结果
3. Agent 第 2 轮：
   • 解析文件列表
   • 生成结构化总结：

   当前目录包含以下文件和子目录：
      
   ## 文件：
   - .env.example - 环境变量配置示例文件
   - QUICKSTART.md - 快速开始指南
   - agent.py - 主要的智能体脚本
      
   ## 子目录：
   - config/ - 配置文件目录
   - docs/ - 文档目录
   - models/ - 模型相关文件目录
   - tools/ - 工具函数目录
   

测试结果：

• ✅ 完整循环正常运行
• ✅ 正确执行 bash 命令
• ✅ 理解命令输出
• ✅ 生成清晰的结构化总结

4.4 性能评估

响应速度：

• 单次 API 调用：~1-2秒
• 完整循环（2轮）：~3-4秒

输出质量：

• 理解能力：⭐⭐⭐⭐⭐
• 格式遵守：⭐⭐⭐⭐⭐
• 内容质量：⭐⭐⭐⭐⭐

成本：

• 简单任务（列出文件）：~100 tokens
• 估算成本：<¥0.001/次

五、项目管理：Git + GitHub

5.1 仓库初始化

# 初始化本地仓库
git init
git add .
git commit -m "feat: 初始化 MeowCode Agent 项目"

# 创建 GitHub 仓库并推送
gh repo create meowcode --public --source=. --push

仓库地址：https://github.com/AriesOxO/meowcode

5.2 目录结构

meowcode/
├── agent.py              # 主入口
├── models/               # LLM 提供商
│   ├── base.py          # 抽象基类
│   ├── deepseek.py      # DeepSeek 实现
│   └── factory.py       # 工厂函数
├── tools/                # 工具系统
│   ├── execute.py       # 命令执行
│   └── file_ops.py      # 文件操作
├── utils/                # 工具函数
│   ├── parser.py        # Action 解析
│   └── config.py        # 配置加载
├── config/               # 配置文件
│   └── config.example.yaml
├── docs/                 # 文档
│   ├── 设计/            # 架构设计文档
│   ├── 参考文档/        # 学习资料
│   ├── 测试/            # 测试报告
│   └── blog/            # 开发博客
└── requirements.txt      # 依赖（只有 2 个！）

5.3 代码统计

Python 文件：12 个
代码行数：~300 行（核心）
总行数：2932 行（含文档）
提交数：3 次
开发时间：1 天

六、遇到的问题与解决

6.1 Windows 编码问题

现象：UnicodeEncodeError: 'gbk' codec can't encode character

原因：Windows 默认使用 GBK 编码，无法显示 emoji

解决：

import sys
import io

if sys.platform == 'win32':
    sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8')

6.2 依赖管理

初始只需要 openai，后来发现配置系统需要 pyyaml：

openai>=1.0.0
pyyaml>=6.0

极简依赖策略：能用标准库就不加依赖。

总结

关键决策

1. Python + DeepSeek：开发速度快，成本极低
2. 抽象层设计：为未来多模型支持打好基础
3. 极简依赖：只有 2 个外部依赖
4. CLI 优先：简单高效，适合开发者

技术亮点

1. 300 行核心代码实现完整 Agent 循环
2. 工厂模式支持多模型扩展
3. 模块化设计，职责清晰
4. 测试完备：API/逻辑/流程 三层验证

成本优势

DeepSeek 让个人开发者也能负担 AI Agent：

• 单次调用：<¥0.001
• 100 次修复：¥0.18
• vs Claude：便宜 300 倍

下一步计划

• 添加代码搜索功能
• 实现错误重试机制
• 集成智谱 GLM
• PyInstaller 打包
• 跨平台测试

项目地址：https://github.com/AriesOxO/meowcode

欢迎 Star 和贡献！下一篇将记录代码搜索功能的实现过程。

GitHub Profile 是开发者的门面，但很多人（包括我）设置完就忘了维护。这次用 Claude Code 做了一次深度体检，发现了不少隐患，顺手全部修复。

一、问题诊断：你的主页可能也有这些坑

1.1 数据硬编码，悄悄过时

之前的 README 用手写的 shields.io badge 展示统计：

![公开仓库](https://img.shields.io/badge/公开仓库-35-blue)
![总Stars](https://img.shields.io/badge/总Stars-31-yellow)

问题是这些数字是写死的。实际检查发现：

数据不一致会给访问者留下「不维护」或「数据造假」的印象。这是最容易被忽视的隐患——静态 badge 永远不会自动更新。

1.2 技术栈过于宽泛

列了 Rust/Go/Java/Python/C + 前端全家桶，但公开仓库主要是 Rust 和 Python。没有项目佐证的技术标签反而降低可信度。

1.3 缺少活跃度证明

没有贡献日历、连续提交记录等动态组件。对独立开发者来说，展示持续活跃比展示技术栈标签更有说服力。

1.4 访问计数器不可靠

用了 count.getloli.com 的第三方服务，key 是 :meow 而不是用户名，稳定性存疑。

二、动态统计：告别手动更新

2.1 精选项目用 shields.io 动态 badge

shields.io 提供基于 GitHub API 的动态 badge，全球 CDN 分发，非常稳定：

![Stars](https://img.shields.io/github/stars/AriesOxO/piz?style=flat-square)

这个 badge 会实时反映仓库的 star 数，不需要手动维护。

2.2 GitHub Stats 卡片

github-readme-stats 提供漂亮的统计卡片，包括总 star、commit 数、PR 数、贡献评级等。但公共实例 github-readme-stats.vercel.app 有速率限制，高峰期经常加载失败。

2.3 Streak 统计

连续提交记录用 streak-stats.demolab.com，由原作者 DenverCoder1 官方维护，比旧的 herokuapp 实例稳定得多：

[![GitHub Streak](https://streak-stats.demolab.com?user=AriesOxO&theme=dark&hide_border=true)](https://git.io/streak-stats)

三、自部署 Vercel 实例：彻底解决加载问题

公共 github-readme-stats.vercel.app 实例的速率限制是个老问题。根本解决方案是自己部署一个实例。

3.1 部署步骤

1. Fork 仓库：gh repo fork anuraghazra/github-readme-stats --clone=false
2. 生成 GitHub Token：Settings → Fine-grained tokens → Public Repositories (read-only)
3. Vercel 部署：Import fork 的仓库，环境变量加 PAT_1 = <token>
4. 获取专属域名：部署完成后 Vercel 分配独立域名

3.2 替换 URL

部署完成后，把 README 中所有 github-readme-stats.vercel.app 替换为自己的域名：

![Stats](https://your-instance.vercel.app/api?username=AriesOxO&show_icons=true&theme=dark&hide_border=true)
![Top Langs](https://your-instance.vercel.app/api/top-langs/?username=AriesOxO&layout=compact&theme=dark&hide_border=true)

自己的实例没有共享速率限制，图片加载问题彻底解决。

四、访问计数器替换

将不稳定的第三方计数器换成 komarev.com/ghpvc，绑定自己的 GitHub 用户名：

![profile views](https://komarev.com/ghpvc/?username=AriesOxO&style=flat-square&color=blue)

总结

1. 数据要动态：任何会变化的数字都不应该硬编码，用 API 驱动的 badge 代替
2. Bio 要有信息量：3 秒让陌生人判断你是谁，别浪费这个高曝光位
3. 公共服务有瓶颈：依赖第三方免费实例要有 Plan B，自部署是最优解
4. 定期体检：Profile 设置完容易忘记维护，数据会悄悄过时

本文分享我们的解决方案：一套可选择、可合并、可跨平台的 Claude Code 环境管理工具。

一、核心思路

我们把 Claude Code 的配置做版本化管理，但不是简单的”备份-恢复”，而是围绕四个原则设计：

1. 配置模块化 — settings.json 拆成独立片段（API、代理、权限、插件……），按需组合
2. 智能合并 — 不覆盖已有配置，而是深度合并，保留用户自定义内容
3. 环境感知 — 自动检测系统环境变量，已有的不重复写入
4. 敏感信息分离 — 密钥通过 .env 管理，不入仓库

二、模块化 Settings

一个完整的 settings.json 可能有几十行，但换电脑时未必全都需要。我们把它拆成独立片段：

settings.d/
├── 01-env-api.json       # API Token、Base URL
├── 02-env-proxy.json     # 代理（国内环境需要，海外不需要）
├── 03-permissions.json   # 权限模式
├── 04-hooks.json         # 自动化 Hooks
├── 05-plugins.json       # 插件列表
└── 06-preferences.json   # 主题等偏好

安装时选 1,3,5,6，跳过代理和 Hooks——因为新机器的网络环境和工作流可能不同。每个片段是一个独立的 JSON 文件，包含 description 字段用于安装时展示说明。

三、合并而非覆盖

如果目标机器已经有 settings.json（比如你手动配了一些东西），脚本不会直接覆盖，而是：

1. 以已有文件为基础
2. 把选中的模块深度合并进去
3. 新增字段追加，同名字段覆盖
4. 用户原有的自定义配置不丢失

同样，CLAUDE.md 已存在时会询问确认，默认不覆盖。安装前还会自动备份原有配置到带时间戳的目录中，确保可回滚。

四、环境变量智能检测

很多人的 API Token 是通过系统环境变量配置的，不需要写进 settings.json。脚本会自动检测：

• 系统已有 ANTHROPIC_AUTH_TOKEN → 跳过，不写入 settings.json
• 系统没有但 .env 中有 → 替换后写入
• 都没有 → 保留 ${...} 占位符，提示手动编辑

两种配置方式共存，不冲突。这解决了一个常见问题：团队共享配置仓库时，每个人的 Token 来源不同。

五、实现方案

最终用 Bash + PowerShell 双版本脚本，覆盖 macOS/Linux/Windows。核心依赖只有 git 和 Node.js（用于 JSON 深度合并）。

仓库结构：

├── bootstrap.sh / .ps1     # 远程一键安装（curl | bash）
├── install.sh / .ps1       # 本地安装脚本
├── .env.example            # 敏感信息模板（可选）
├── profiles/default/       # 配置集
│   ├── CLAUDE.md
│   ├── instructions/
│   └── settings.d/
└── skills/                 # 所有技能（安装时选择）

新电脑上一行命令搞定：

# Linux/macOS
curl -fsSL https://raw.githubusercontent.com/<你的用户名>/<仓库名>/master/bootstrap.sh | bash

# Windows PowerShell
irm https://raw.githubusercontent.com/<你的用户名>/<仓库名>/master/bootstrap.ps1 | iex

安装流程：检测配置目录 → 备份原有配置 → 选择 settings 模块 → 选择 skills → 智能合并生成。

总结

1. 模块化：配置拆片段，按需组合，不同环境选不同模块
2. 非破坏性：合并而非覆盖，保留用户已有的自定义配置
3. 环境感知：系统变量和 .env 两种方式兼容，不冲突
4. 跨平台：Bash + PowerShell 双版本，一套仓库三端通用
5. 一键恢复：远程 bootstrap 脚本，新电脑一行命令搞定

AI 编码助手的配置管理本质上和 dotfiles 管理是同一个问题，但多了”模块化选择”和”智能合并”的需求。不是所有配置都适合所有环境，也不是每次安装都该从零开始。如果你也有类似的需求，不妨参考这套思路，按自己的实际情况落地。

一、Playwright 驱动的问题发现

这次优化的起点不是用户反馈，而是自动化截图分析。我们编写了一套 Playwright 脚本，在 iPhone 14 (390px) 和 375px 两种视口下对所有前台页面截图，然后逐帧对比分析问题。

核心发现：

这个分析方法本身就是一个值得分享的经验：不要靠感觉判断移动端适配质量，用真实设备视口的截图说话。

二、可折叠筛选栏：一行摘要 + 展开面板

2.1 问题：筛选栏吞掉了整个首屏

移动端纵向排列 4-6 个筛选字段 + 按钮，高度轻松超过 400px。在 844px 高度的 iPhone 14 上，减去 header (44px) 和 tabbar (62px)，可用高度只有 738px——筛选栏直接占了一半以上。

2.2 方案：双模式切换

我们实现了「收起态」和「展开态」两种模式：

<!-- 收起态：一行摘要 -->
<div v-if="!filterExpanded" class="filter-summary" @click="filterExpanded = true">
  <div class="filter-tags">
    <el-tag v-if="queryParams.competitionId" size="small" closable
      @close.stop="clearSingleFilter('competitionId')">
      
    </el-tag>
    <!-- 其他激活的筛选条件 Tag... -->
    <span v-if="!hasActiveFilters" class="no-filter">全部评论</span>
  </div>
  <el-button text type="primary" size="small">
    <el-icon><Filter /></el-icon>筛选
  </el-button>
</div>

<!-- 展开态：完整表单 -->
<FilterBar v-if="filterExpanded" class="filter-container-mobile">
  <!-- 筛选字段 + 重置/完成按钮 -->
</FilterBar>

关键设计决策：

1. Tag 可单独关闭：点击 Tag 上的 × 可直接清除某个筛选条件，无需展开面板
2. 桌面端不受影响：通过 .desktop-filter / .mobile-filter 的 display: none 在 768px 断点切换
3. 小说类型用 Chip 按钮组：从 el-select 改为 el-check-tag，减少一次点击

效果：首屏从只能看到筛选栏 → 直接看到 3 张评论卡片 + FAB 按钮。

三、移动端卡片视图：替代不可用的表格

3.1 资格统计页：从零到完整

修复前，10 列表格在移动端只能看到 ID、用户名和操作按钮——笔名、届次、等效评论、实际评论、总字数、资格状态、更新时间全部丢失。

我们参照前台评论页已有的 desktop-table / mobile-card-list 双视图模式，为资格统计页设计了卡片布局：

<div class="stat-card">
  <div class="card-header">
    <div class="card-user">
      <span class="user-name"></span>
      <span class="user-id"></span>
    </div>
    <el-tag :type="row.isQualified ? 'success' : 'danger'" size="small">
      
    </el-tag>
  </div>
  <div class="card-body">
    <!-- 2×2 网格：届次、等效评论、实际评论、总字数 -->
  </div>
  <div class="card-footer">
    <span class="update-time"></span>
    <el-button link type="primary" size="small" @click="handleRecalculateUser(row)">重算</el-button>
  </div>
</div>

3.2 管理员评论页：同样的方案

管理员评论页的 el-table 也严重截断，用相同思路添加了卡片视图，每张卡片展示标题+类型、笔名/届次/评分、评论预览、编辑/删除操作。

四、排行榜资格详情：从 80% 抽屉到全屏重构

4.1 问题

点击排行榜中的评论者名字，会打开一个 80% 宽度的右侧抽屉显示资格详情。这个抽屉在移动端有多个致命问题：

• 5 列统计卡片网格崩塌
• 7 列明细表格完全截断
• 没有关闭按钮
• 左侧露出排行榜内容，视觉干扰

4.2 方案：条件渲染两套抽屉

<!-- 桌面端：保持原有右侧抽屉 -->
<el-drawer v-if="!isMobile" v-model="showDetail" size="80%">
  <!-- 桌面版内容不变 -->
</el-drawer>

<!-- 移动端：全屏底部抽屉 -->
<el-drawer v-if="isMobile" v-model="showDetail" direction="btt" size="100%">
  <div class="mobile-detail-header">
    <el-button text @click="showDetail = false">
      <el-icon><ArrowLeft /></el-icon>
    </el-button>
    <span>资格详情</span>
  </div>
  <div class="mobile-detail-body">
    <!-- 状态卡片：用户名 + 届次 + 资格Tag -->
    <!-- 统计 2列网格：等效/字数/总评/深评 -->
    <!-- 综合检查：列表 + 通过/未过 Tag -->
    <!-- 明细：卡片列表替代 7 列表格 -->
  </div>
</el-drawer>

关键改动：

• 统计从 5 列 → 2 列网格
• 明细表格 → 每条一张卡片（标题+类型/字数+权重+深评+累计）
• 综合检查从嵌套括号文字 → 结构化列表 + Tag
• 标题从「爱丽丝-第5届-未参赛」纯文字 → 用户名大字 + 届次小字 + 状态 Tag

五、暗黑模式补全

5.1 底部导航栏

暗黑模式下 tabbar 仍为 rgba(255, 255, 255, 0.96)——在深色页面上非常刺眼。

由于 FrontLayout 使用了 <style scoped>，html.dark 选择器不生效。解决方案是新增一个非 scoped 的 <style> 块：

<style>
html.dark .front-layout .mobile-tabbar {
  background: rgba(30, 30, 46, 0.96);
  border-top-color: rgba(140, 150, 200, 0.15);
}
</style>

5.2 移动端暗黑切换入口

移动端 header 只有标题和用户头像，没有 ThemeSwitch。直接在 .mobile-actions 中添加已有的 <ThemeSwitch /> 组件即可。

六、邮箱自助修改功能

6.1 需求

原来修改邮箱需要联系管理员。我们实现了验证码自助修改流程。

6.2 后端：两个新 API

// POST /api/users/profile/email/send-code
func SendEmailChangeCode(c *gin.Context) {
    // 1. 校验新邮箱 ≠ 当前邮箱
    // 2. 校验新邮箱未被其他用户注册（唯一性）
    // 3. 复用 EmailService.SendVerificationCode(newEmail, "change_email")
}

// PUT /api/users/profile/email
func ConfirmEmailChange(c *gin.Context) {
    // 1. EmailService.VerifyCode 验证验证码
    // 2. 再次校验唯一性（防并发）
    // 3. 更新邮箱
}

复用了现有的 EmailService，无需新建任何服务。唯一性校验做了两次——发送时一次（用户体验），确认时再一次（安全防并发）。

6.3 前端交互

邮箱区域从 disabled input 改为纯文本 + 「修改」链接，点击后展开验证码流程：

admin@laping.test  修改    ← 默认态
     ↓ 点击修改
[请输入新邮箱      ] [发送验证码]  ← 编辑态
[请输入验证码      ]              ← 发送后出现
        [取消]  [确认修改]

60 秒倒计时防止频繁发送，cancelEmailEdit() 可随时退出。

七、个人信息页 UI 优化

7.1 表单 label 上下布局

移动端 640px 以下，表单 label 从左侧 100px 固定宽度改为位于输入框上方，输入框全宽。用 :deep() 覆盖 Element Plus 默认布局。

7.2 密码卡片可折叠

修改密码三个输入框默认展示占据大量空间。改为移动端默认收起，点击标题展开：

<div class="clickable-header" @click="passwordExpanded = !passwordExpanded">
  <span>修改密码</span>
  <el-icon :class="{ 'is-rotated': passwordExpanded }"><ArrowDown /></el-icon>
</div>
<div v-show="passwordExpanded || !isMobileView">
  <!-- 密码表单 -->
</div>

桌面端通过 || !isMobileView 始终展示，箭头图标用 CSS 隐藏。

八、样式一致性统一

跨 4 个页面的可折叠筛选栏最初存在不一致：

• label 最小宽度：50px / 60px / 70px / 80px
• label 文字：「届次」vs「比赛届数」，「类型」vs「小说类型」
• 完成按钮：有的带 Search 图标，有的不带

统一标准后：

• min-width: 70px
• 同名字段用相同文字（比赛届数、小说类型、笔名、小说标题）
• 完成按钮统一 type="primary" 蓝色，不带图标
• 小说类型统一使用 el-check-tag Chip 按钮组

总结

1. Playwright 截图分析法：不要靠感觉判断移动端适配，用真实视口截图发现问题比手动测试更高效
2. 双视图模式：desktop-table + mobile-card-list 是表格页面移动端适配的通用方案
3. 可折叠筛选：移动端首屏寸土寸金，筛选栏必须可以收起
4. scoped 与 html.dark：暗黑模式样式需要放在非 scoped <style> 块中
5. 条件渲染两套布局：v-if="isMobile" 比 CSS 媒体查询更灵活，适合结构差异大的场景
6. 复用现有服务：邮箱修改功能复用了已有的 EmailService，零新依赖
7. 统一设计规范：跨页面组件样式必须从第一天就定标准，否则越做越散

痛点在哪

飞牛NAS（fnOS）基于 Linux，硬件控制走的是标准的 hwmon 子系统。理论上可以直接写 sysfs 文件来控制风扇，但实际使用中有几个现实问题：

1. 噪音与散热的平衡难：默认的 BIOS 风扇策略太粗暴，低温全速或者高温才启动，没有中间地带
2. 机型差异大：不同飞牛机型用的主板芯片不同（ITE、Nuvoton、Fintek），控制方式有细微差别
3. 缺少可视化管理：命令行脚本虽然能用，但调曲线、看温度都不方便
4. 安全风险：手动控制风扇如果程序崩了，风扇可能停转导致硬件过热

我需要的是一个安装即用、有 Web 界面、自带安全保护的风扇控制应用。

目标定义

经过需求分析，我确定了几个核心目标：

技术选型

为什么用 Python？

这个项目的核心是读写 sysfs 文件和运行一个轻量 HTTP 服务，不需要高性能计算。Python 标准库自带 http.server、json、threading，完全够用。最关键的是——零第三方依赖。

NAS 环境特殊，用户不一定有 pip，也不想装一堆包。Python 3.11+ 在飞牛系统上是预装的，拿来就能用。

前端方案：纯 HTML + CSS + 原生 JavaScript，单文件。不需要 Node.js 构建工具链，不需要 npm install，打开就能用。

整体技术栈：

后端：Python 3.11+（标准库 only）
前端：HTML + CSS + Vanilla JS（单文件）
硬件接口：Linux hwmon sysfs
打包：FPK（飞牛应用包格式）
CI：GitHub Actions
测试：unittest（120 个测试用例）

项目结构规划

fnOS-fan-control/
├── src/
│   ├── app/bin/           # Python 应用核心（5 个模块）
│   │   ├── main.py        # 入口（启动、信号处理、OOM 保护）
│   │   ├── hardware.py    # 硬件抽象层（hwmon 探测、PWM 读写）
│   │   ├── fan_controller.py  # 风扇控制核心（温控逻辑）
│   │   ├── config_manager.py  # 配置管理（校验、线程安全）
│   │   ├── web_server.py  # REST API 服务
│   │   └── static/index.html  # Web 管理界面
│   ├── cmd/               # FPK 生命周期脚本（9 个）
│   └── manifest           # FPK 包元数据
├── tests/                 # 120 个单元 + 集成测试
├── scripts/               # 构建和清理脚本
└── .github/workflows/     # CI 自动构建

模块划分的原则是单一职责：硬件层只管读写 sysfs，控制层只管温控逻辑，配置层只管数据校验，Web 层只管 HTTP 请求。模块之间通过明确的接口交互，任何一个模块出问题都不会拖垮整个系统。

开发计划

整个开发分为 6 个阶段：

1. 基础框架 — 硬件探测、配置管理、单风扇控制
2. Web 管理界面 — REST API、前端页面、实时监控
3. 温控曲线编辑 — SVG 可视化、自动生成、手动微调
4. FPK 打包 — 生命周期脚本、安装向导、权限配置
5. 多设备适配 — 通用 hwmon 探测、多区域控制
6. 测试与文档 — 单元测试、集成测试、完整文档

下一篇预告

下一篇会聊架构设计的核心决策：为什么选择「sysfs 就是抽象层」的设计哲学，如何用最少的代码实现多芯片兼容，以及多层安全机制是怎么设计的。

项目地址：fnOS-fan-control on GitHub（MIT 许可证）

核心设计哲学：sysfs 就是抽象层

做硬件控制最容易掉进去的坑是过度抽象。一开始我也想过给不同芯片写 Driver 类，搞一套继承体系：

# 反面教材：过度设计
class FanDriver(ABC): ...
class IT8772Driver(FanDriver): ...
class NCT6776Driver(FanDriver): ...

后来想明白了——Linux hwmon 子系统已经做了这件事。不管底层是 ITE IT8772E 还是 Nuvoton NCT6776，在 /sys/class/hwmon/ 下看到的接口都是统一的：

/sys/class/hwmon/hwmonX/
├── name            # 芯片名称
├── pwm1            # PWM 值 (0-255)
├── pwm1_enable     # 控制模式 (1=手动, 2=自动)
├── fan1_input      # 转速 (RPM)
├── temp1_input     # 温度 (毫摄氏度)
└── temp1_label     # 温度标签

我要做的不是再写一层抽象，而是直接用好 sysfs 这个现成的抽象层。

硬件探测的实现

hardware.py 的核心函数 detect_hwmon_paths() 做的事情很简单：扫描所有 hwmon 设备，找到有 pwm 文件的就认为可以控制。

def detect_hwmon_paths():
    """扫描 /sys/class/hwmon，返回所有可控风扇通道"""
    channels = {}
    for hwmon_dir in Path('/sys/class/hwmon').iterdir():
        # 找到所有 pwmN 文件
        for pwm_file in sorted(hwmon_dir.glob('pwm[0-9]*')):
            if pwm_file.name.endswith('_enable'):
                continue
            channel_name = pwm_file.name  # pwm1, pwm2, ...
            # 多芯片时加前缀避免冲突
            if channel_name in channels:
                chip_name = (hwmon_dir / 'name').read_text().strip()
                channel_name = f"{chip_name}_{channel_name}"
            channels[channel_name] = {
                'pwm_path': str(pwm_file),
                'enable_path': str(pwm_file) + '_enable',
                'chip': chip_name
            }
    return channels

这个设计的好处是对未知芯片天然兼容——只要内核驱动加载了，hwmon 接口就在那里，我不需要提前知道用户的硬件型号。

温度读取的优先级策略

CPU 温度的读取需要一点技巧。不同平台的温度 label 不一样：

代码会按优先级扫描 label，找到第一个匹配的就用。读不到就返回 None，由上层决定如何处理。

硬盘温度走 drivetemp 内核模块，安装时自动 modprobe drivetemp，之后硬盘温度就出现在 hwmon 里了。

温控核心：线性插值 + 多层保护

温控曲线的工作原理

用户定义一组温度-转速节点，比如：

30°C → 20%
50°C → 40%
65°C → 70%
80°C → 100%

实际温度落在两个节点之间时，用线性插值计算 PWM 值：

def interpolate(temp, curve):
    """线性插值计算 PWM 值"""
    if temp <= curve[0]['temp']:
        return curve[0]['pwm_percent']
    if temp >= curve[-1]['temp']:
        return curve[-1]['pwm_percent']

    for i in range(len(curve) - 1):
        t0, p0 = curve[i]['temp'], curve[i]['pwm_percent']
        t1, p1 = curve[i+1]['temp'], curve[i+1]['pwm_percent']
        if t0 <= temp <= t1:
            ratio = (temp - t0) / (t1 - t0)
            return p0 + ratio * (p1 - p0)

这样风扇转速会随温度平滑过渡，不会出现突然加速的情况。

控制循环

fan_controller.py 的主循环每 N 秒（默认 2 秒）执行一次：

读取所有温度 → 遍历每个区域 → 根据模式计算 PWM → 写入 sysfs

关键设计决策：单线程遍历所有区域。NAS 通常只有 1-3 个风扇区域，单线程足够，避免了多线程同步的复杂度。温度数据一次读取后所有区域共享，减少 sysfs 读次数。

多层安全机制

这是整个项目最重要的部分。硬件控制程序如果出问题，后果可能是硬件损坏。我设计了 5 层保护：

第一层：绝对最低转速

ABSOLUTE_MIN_PWM = 26  # 约 10%，风扇不会完全停转

无论用户怎么配置，PWM 值永远不会低于 26。

第二层：温度读取失败保护

连续 3 次失败 → 所有区域全速运转 (PWM=255)
连续 5 次失败 → 降级到默认保守曲线

宁可吵一点，也不能让硬件过热。

第三层：PWM 写入异常保护

写 sysfs 文件可能因为各种原因失败（驱动问题、权限问题）。连续 3 次写入失败后，该区域自动降级。

第四层：pwm_enable 自愈

有些 BIOS 会定期把 pwm_enable 从 1（手动）改回 2（自动）。控制循环每次执行时都会检查并修正这个值。

第五层：看门狗

主进程之外有一个独立的 Bash 看门狗进程。如果主进程意外崩溃，看门狗会在 5 秒内检测到并恢复 pwm_enable=2，让 BIOS 接管风扇控制。

正常退出：SIGTERM → cleanup() → restore_safe_state()
异常崩溃：看门狗 5s 内检测 → restore_safe_state()
卸载：uninstall 脚本 → 扫描恢复所有 pwm_enable=2

Web 管理界面

后端：12 个 REST API

基于 Python 标准库的 http.server，用 ThreadingMixIn 支持并发请求。

GET  /api/status         # 实时温度、转速、PWM、模式
GET  /api/config         # 当前配置
POST /api/config         # 更新配置
GET  /api/hardware       # 硬件探测结果
POST /api/mode           # 切换运行模式
POST /api/curve/generate # 自动生成温控曲线
GET  /api/logs           # 事件日志（最近 100 条）
POST /api/auth/login     # 登录认证

安全方面：POST body 限制 4KB 防止滥用，可选密码认证（Cookie + Header 双模式），所有异常捕获不泄露堆栈信息。

前端：单文件 SPA

整个前端是一个 index.html 文件，约 2000 行，包含 HTML + CSS + JavaScript。

页面结构：

┌─ 顶部状态栏（应用名 + 运行状态指示灯）──────┐
├─ 告警条（降级/硬件未探测/连接中断）──────────┤
├─ 状态卡片 4 列（CPU温度/硬盘温度/转速/PWM）─┤
├─ 运行模式切换（4 个按钮）────────────────────┤
├─ 温控曲线（SVG 图 + 折叠编辑器）─────────────┤
├─ ▶ 高级设置（折叠面板）──────────────────────┤
├─ ▶ 运行日志（折叠面板）──────────────────────┤
└─ ▶ 使用说明（折叠面板）──────────────────────┘

深色主题配色：背景 #0f1923，卡片 #1a2736，强调色 #00b4d8。温度数字会变色：<50°C 绿色 / 50-65°C 橙色 / >65°C 红色。

交互亮点：

• 实时轮询刷新（按配置的轮询间隔）
• 连接失败时指数退避重试（上限 30 秒）
• 温控曲线 SVG 实时预览
• Toast 通知反馈操作结果

配置系统的设计

配置采用 JSON 格式，支持两种版本：

v1 扁平格式（向后兼容，单风扇场景）：

{
  "mode": "auto",
  "poll_interval": 2,
  "temp_source": "cpu",
  "curve": [
    {"temp": 30, "pwm_percent": 20},
    {"temp": 80, "pwm_percent": 100}
  ]
}

v2 zones 格式（多区域场景）：

{
  "zones": [
    {
      "id": "zone_cpu",
      "name": "CPU 风扇",
      "channels": ["pwm1"],
      "temp_source": "cpu",
      "mode": "auto",
      "curve": [...]
    },
    {
      "id": "zone_disk",
      "name": "硬盘风扇",
      "channels": ["pwm2"],
      "temp_source": "disk",
      "mode": "auto",
      "curve": [...]
    }
  ]
}

config_manager.py 在运行时自动将 v1 格式包装成单区域的 v2 格式，不改写配置文件。这样老用户升级后配置文件不变，程序内部统一用 zones 格式处理。

下一篇预告

最后一篇聊多设备适配的实战经验：不同芯片的坑、FPK 打包的注意事项、测试策略，以及项目的整体复盘。

项目地址：fnOS-fan-control on GitHub（MIT 许可证）

多设备适配：芯片差异与统一方案

支持的芯片家族

经过测试和社区反馈，目前兼容的芯片包括：

踩过的坑

坑 1：pwm_enable 的值在不同芯片上含义不完全一致

大多数芯片：1 = 手动控制，2 = 自动（BIOS 控制）。但个别芯片还有 0（全速）、3（温控曲线）等值。

解决方案：统一使用 pwm_enable=1 进入手动模式，退出时统一恢复为 2。不依赖芯片特有的自动模式。

坑 2：多芯片时通道名冲突

两块芯片都有 pwm1，直接用名字会冲突。解决方案是检测到冲突时自动加芯片名前缀：

chip0: it8772e → it8772e_pwm1
chip1: nct6776 → nct6776_pwm1

坑 3：BIOS 会抢回风扇控制权

某些 BIOS 会定期把 pwm_enable 从 1 改回 2。如果不处理，用户会发现风扇控制「时灵时不灵」。

解决方案：每个控制周期开始前先检查 pwm_enable，如果被改了就改回来。这就是前面提到的「pwm_enable 自愈」机制。

多区域控制的实现

多区域的核心思想是：每个风扇区域独立运行，互不干扰。

区域 A（CPU 风扇）：绑定 pwm1，跟踪 CPU 温度，使用激进曲线
区域 B（硬盘风扇）：绑定 pwm2，跟踪硬盘温度，使用保守曲线

实现上，控制循环每次迭代：

1. 一次性读取所有温度（CPU + 硬盘）
2. 遍历每个区域，根据区域配置的温度来源取对应温度
3. 按区域自己的模式和曲线计算 PWM
4. 写入对应的 sysfs 文件

区域级降级也是独立的——区域 A 的 PWM 写入失败不影响区域 B。

测试策略：120 个测试用例

测试结构

tests/
├── mock_hardware.py        # 模拟硬件环境
├── test_hardware.py        # 硬件抽象层（30 个测试）
├── test_config_manager.py  # 配置管理（25 个测试）
├── test_fan_controller.py  # 控制逻辑（27 个测试）
└── test_web_server.py      # Web API + 认证（28 个测试）

Mock 硬件

真实测试需要 NAS 硬件，但开发环境是普通 PC。mock_hardware.py 模拟了完整的 hwmon sysfs 结构：

class MockHardware:
    """在 /tmp 下创建模拟的 hwmon 文件结构"""

    def create_chip(self, name='it8772e', channels=1):
        # 创建 /tmp/hwmon0/name, pwm1, pwm1_enable, fan1_input 等文件
        # 支持读写，行为与真实 sysfs 一致

支持模拟 IT8772、NCT6776 和自定义芯片，可以测试多芯片冲突等边界场景。

测试重点

硬件层测试：

• 芯片探测（单芯片、多芯片、无芯片）
• CPU 温度读取（Intel label、AMD label、ARM thermal）
• PWM 读写（正常值、边界值、文件不存在）
• 通道名冲突处理

控制逻辑测试：

• 线性插值计算（精确到小数点）
• 温度边界值（低于最低节点、高于最高节点）
• 模式切换（四种模式互相切换）
• 降级触发（温度读取失败 N 次后自动降级）
• 全速保护（温度异常时的应急响应）
• 除零保护（两个节点温度相同时不崩溃）

配置管理测试：

• v1/v2 格式兼容
• 无效值自动回退默认值
• 配置文件损坏恢复
• 并发读写安全

Web API 测试：

• 所有 12 个端点的正常流程
• 输入校验（超大 body、非法 JSON、越界参数）
• CORS 头部正确性
• 密码认证流程

FPK 打包

FPK 是飞牛的应用包格式，类似 Synology 的 SPK。一个 FPK 包需要：

生命周期脚本

cmd/
├── main                    # start / stop / status
├── install_init            # 安装前检查
├── install_callback        # 安装后初始化
├── upgrade_init            # 升级前准备
├── upgrade_callback        # 升级后恢复
├── uninstall_init          # 卸载前清理
├── uninstall_callback      # 卸载后清理
├── config_init             # 配置初始化
└── config_callback         # 配置回调

关键脚本逻辑：

main（启动/停止）：

• 启动时先启动看门狗进程，再启动主应用
• 停止时先停主应用，再停看门狗
• status 检查主进程是否存活

install_callback（安装后）：

• 检查 Python 3.11+ 是否可用
• 加载 drivetemp 内核模块（硬盘温度监控）
• 设置正确的文件权限

uninstall_init（卸载前）：

• 停止服务
• 扫描所有 hwmon 设备，恢复 pwm_enable=2
• 确保卸载后风扇回到 BIOS 控制

安装向导

FPK 支持安装时弹出配置向导。我配置了一个端口选择向导，让用户在安装时就能指定 Web 界面的端口号，避免与其他服务冲突。

CI 自动构建

GitHub Actions 自动打包 FPK：

# .github/workflows/build-fpk.yml
- name: Build FPK
  run: bash scripts/build-fpk.sh
- name: Upload artifact
  uses: actions/upload-artifact@v4
  with:
    name: fnos-fan-control.fpk
    path: dist/*.fpk

每次 push 或 tag 都会自动构建，Release 页面可以直接下载。

项目复盘

做对了的事

1. 零依赖策略

从第一天就决定不引入第三方包，事后证明这是对的。NAS 用户的环境各不相同，零依赖意味着只要有 Python 就能跑，安装从不出问题。

2. 安全优先设计

安全机制不是事后补的，而是从架构层面就考虑进去的。看门狗、多层降级、最低转速保护，这些在第一个版本就有了。硬件控制程序出问题的代价太大，安全必须是一等公民。

3. sysfs 就是抽象层

没有搞复杂的驱动类继承体系，直接利用 Linux hwmon 的统一接口。代码简单，兼容性反而更好。

4. 渐进式多区域

v1 单风扇和 v2 多区域共存，老配置不用改，新功能可选启用。运行时自动适配，没有迁移负担。

可以改进的地方

1. 前端多区域支持

后端的多区域功能已经完整，但前端还没有完全跟上。目前多区域配置需要手动编辑 JSON。这是 v1.2 的重点。

2. 温度历史图表

目前只有实时数据，没有历史趋势图。对于调试温控曲线来说，能看到过去几小时的温度变化会很有帮助。

3. 通知机制

温度告警时能推送通知（飞牛系统通知或邮件）会更实用。

数据总结

写在最后

这个项目解决了一个很小但很实际的问题——让 NAS 安静下来。技术上没有什么高深的东西，就是把 Linux sysfs 接口用好，把异常情况想全，把安全保护做到位。

如果你也在用飞牛NAS，被风扇噪音困扰，欢迎试试这个工具。也欢迎提 Issue 和 PR，特别是不同机型的兼容性反馈。

项目地址：fnOS-fan-control on GitHub（MIT 许可证）

一、暗黑模式：从”能用”到”全量可用”

暗黑模式是这次冲刺中工作量最大的部分。Element Plus 自带暗黑主题支持，但实际落地远没有想象中简单——我们经历了五轮修复才彻底解决问题。

1.1 管理后台：CSS 变量缺失

第一轮修复管理后台。问题很直接：侧边栏、仪表盘、设置页等组件中有大量硬编码的白色背景色。

解决方案是新建 admin-tokens.css，定义暗黑模式下的 CSS 变量：

/* admin-vue/src/theme/admin-tokens.css */
html.dark {
  --app-bg: #141414;
  --app-surface: #1d1e1f;
  --app-surface-alt: #262727;
  --app-text: #e5eaf3;
  --app-text-secondary: #a3a6ad;
  --app-border: #414243;
  --el-card-bg-color: var(--app-surface);
}

然后逐页将 background: #fff 替换为 background: var(--app-surface)。管理后台涉及 6 个组件，替换了 8 处硬编码。

1.2 前台页面：22 处硬编码白色背景

管理后台修完后，发现前台页面（排行榜、评论、投稿等）同样有大量白色背景。这次用相同策略，新建 front-tokens.css 并批量替换，一次处理了 10 个文件中的 22 处硬编码。

1.3 根本性问题：scoped 样式与 html.dark 选择器

前两轮修完后仍然有页面暗黑模式不生效。排查发现了一个根本性问题：

<!-- ❌ 这样写不生效！ -->
<style scoped>
html.dark .my-component {
  background: #1d1e1f;
}
</style>

Vue 的 <style scoped> 会给选择器加上 data-v-xxx 属性限定，导致 html.dark 这种向上跨组件的选择器完全失效。

解决方案：将暗黑模式相关样式从 <style scoped> 中提取到单独的非 scoped <style> 标签中：

<style scoped>
/* 组件常规样式 */
.ranking-card { background: var(--app-surface); }
</style>

<!-- 暗黑模式覆盖必须放在非 scoped 的 style 中 -->
<style>
html.dark .ranking-card { background: var(--app-surface-alt); }
</style>

这次修复涉及排行榜、评论列表、参加比赛、添加评论 4 个核心页面。

1.4 深度修复：ECharts 图表与边角组件

还有 ECharts 统计图表在暗黑模式下文字看不清的问题。通过监听主题切换事件，动态更新图表配色：

// 监听暗黑模式切换
const isDark = useDark()
watch(isDark, () => {
  chart.setOption({
    textStyle: { color: isDark.value ? '#e5eaf3' : '#303133' },
    legend: { textStyle: { color: isDark.value ? '#e5eaf3' : '#606266' } }
  })
})

最终统计：暗黑模式适配共修复 60+ 处样式问题，覆盖全部前台和后台页面。

二、欠债补评论系统 v3 重构

2.1 从三维度到单维度

v2 的欠债系统使用三个维度（等效评论数、实际评论数、字数）来计算欠债，导致规则复杂且用户难以理解。v3 重构为单维度等效评论模型，大幅简化：

• 用户只需要关注一个数字：欠多少条等效评论
• 惩罚规则简化：零评论罚评数、单笔欠债上限、最大禁投届数三个参数可在后台配置
• 前端 DebtManagement.vue 从三列展示改为单列，表头增加帮助 tooltip 解释计算规则

2.2 配置缺失问题

重构后发现后端 InitDefaultSettings 中缺少调度器相关的默认配置，导致欠债补评任务无法正常触发。同时 debt_count 列已被移除但查询代码中仍在引用。两个问题一起修复：

// cmd/server/database/database.go - 补充默认配置
func InitDefaultSettings() {
    defaults := map[string]string{
        "debt_zero_comment_penalty": "2",
        "debt_max_per_entry":        "5",
        "debt_max_ban_periods":      "3",
        // ...调度器配置
    }
    for key, val := range defaults {
        database.DB.FirstOrCreate(&models.Settings{}, models.Settings{Key: key, Value: val})
    }
}

所有测试文件也同步适配了 v3 单维度模型。

三、管理界面全面优化

这次冲刺对管理后台几乎所有页面做了一轮系统性优化。

3.1 侧边栏重组

原来的侧边栏菜单项扁平排列，改为四组分类：概览、内容管理、数据与规则、系统。每个菜单项使用唯一图标，整体视觉更清晰：

<!-- 分组式侧边栏 -->
<el-menu-item-group title="概览">
  <el-menu-item index="/admin/dashboard"><el-icon><Odometer /></el-icon>仪表盘</el-menu-item>
</el-menu-item-group>
<el-menu-item-group title="内容管理">
  <el-menu-item index="/admin/comments">...</el-menu-item>
  <el-menu-item index="/admin/submissions">...</el-menu-item>
</el-menu-item-group>

3.2 操作列瘦身

用户管理和比赛管理页面的操作列原来有多个按钮并排，占用 280-350px 宽度。改为「编辑 + 更多下拉菜单」模式，宽度降到 160px：

<el-table-column label="操作" width="160" fixed="right">
  <template #default="{ row }">
    <el-button size="small" @click="editUser(row)">编辑</el-button>
    <el-dropdown>
      <el-button size="small">更多<el-icon><ArrowDown /></el-icon></el-button>
      <template #dropdown>
        <el-dropdown-menu>
          <el-dropdown-item @click="resetPassword(row)">重置密码</el-dropdown-item>
          <el-dropdown-item @click="toggleBan(row)"></el-dropdown-item>
        </el-dropdown-menu>
      </template>
    </el-dropdown>
  </template>
</el-table-column>

3.3 系统设置页面重构

系统设置页从单栏改为双栏布局，Tab 合并调度器设置，统一保存按钮和全局 loading 状态。同时新增欠债惩罚参数的可视化配置，并补充了 20 个 Playwright E2E 测试用例。

3.4 仪表盘精简

仪表盘清理了 230 行旧代码（包括不再使用的图表和统计项），参赛管理 Tab 的 tooltip 改为动态读取后端配置。

四、文案提示系统

4.1 问题背景

辣评有大量业务规则（等效评论公式、合格条件、欠债惩罚规则等），之前这些文案散落在各个组件中，既难以维护也容易出现不一致。

4.2 集中管理方案

创建 helpTexts.ts 配置文件和 useHelpTexts composable：

// admin-vue/src/config/helpTexts.ts
export const helpTexts = {
  qualification: {
    formula: '等效评论 = 短篇评论×1 + 中篇评论×1.5 + 长篇评论×2',
    condition: '等效评论 ≥ {minEquivalent} 且 实际评论 ≥ {minActual} 且 总字数 ≥ {minWords}',
    tooltip: '合格条件中的阈值可在系统设置中配置'
  },
  debt: {
    penalty: '零评论额外罚 {zeroPenalty} 条，单笔上限 {maxPerEntry} 条',
    ban: '连续欠债 {maxBanPeriods} 届触发禁投'
  }
  // ...共 20 处文案
}

// admin-vue/src/composables/useHelpTexts.ts
export function useHelpTexts(section: string) {
  const settings = useSettingsStore()
  // 动态替换 {minEquivalent} 等占位符为后端配置值
  return computed(() => interpolate(helpTexts[section], settings.config))
}

最终接入了 6 个页面、13 处文案提示，覆盖了所有 P2/P3 级别的业务规则说明。

五、审计日志增强

5.1 覆盖面扩展

原来审计日志只记录 8 种操作类型。这次补充了 15 处写操作的审计记录，覆盖比赛管理、规则管理、评论操作、投稿操作、系统配置、调度器启停等，操作类型扩展到 27 种。

5.2 CSV 导出

新增导出接口，支持按当前筛选条件导出，输出 UTF-8 BOM 编码确保 Excel 直接打开不乱码：

// cmd/server/handlers/audit_handler.go
func ExportAuditLogs(c *gin.Context) {
    // ... 筛选逻辑同列表接口
    c.Header("Content-Type", "text/csv; charset=utf-8")
    c.Header("Content-Disposition", "attachment; filename=audit-logs.csv")
    // 写入 BOM
    c.Writer.Write([]byte{0xEF, 0xBB, 0xBF})
    writer := csv.NewWriter(c.Writer)
    writer.Write([]string{"时间", "操作人", "操作类型", "操作对象", "详情"})
    // ...
}

5.3 前端页面优化

审计日志页面做了 5 项改进：操作类型全中文化、分组筛选下拉、JSON 详情格式化展示、操作对象可读化（从 user:123 变为显示用户名）、增加导出按钮。

六、用户手册 v2.0

6.1 全面重写

原有的 10 章英文手册全部替换为 13 章中文文档，按照实际功能模块重新组织：

1. 系统概述
2. 注册与登录
3. 比赛与投稿
4. 评论与评分
5. 排行榜与统计
6. 任务与资格
7. 用户管理
8. 规则管理
9. 投稿管理
10. 欠债管理
11. 系统设置
12. 审计日志
13. 常见问题

新增了排行榜、任务追踪、审计日志三个之前缺失的章节，并补充了暗黑模式的适配样式。

七、星级评分组件优化

评论打分从原来的自由数字输入改为 1-5 星评分，带渐变色和文字描述：

<el-rate
  v-model="form.rating"
  :texts="['很差', '较差', '一般', '较好', '很好']"
  :colors="['#F56C6C', '#E6A23C', '#909399', '#67C23A', '#409EFF']"
  show-text
  :allow-half="false"
/>

代评弹窗中的评分组件也同步升级，保持前后台交互一致。

八、工程化改进

8.1 版本号单一来源

之前版本号分散在 package.json、.env、config/index.ts 三处，容易出现不一致。重构为 version.json 单一来源：

{
  "version": "0.9.0",
  "versionName": "辣评",
  "buildDate": "2026-03-29"
}

构建时通过 prebuild 脚本自动同步到 package.json：

// admin-vue/scripts/sync-version.js
const version = require('../version.json')
const pkg = require('../package.json')
pkg.version = version.version
fs.writeFileSync('package.json', JSON.stringify(pkg, null, 2))

8.2 部署脚本增强

部署脚本新增用户手册上传步骤，确保文档与代码同步部署。

8.3 CHANGELOG

正式建立版本变更日志，记录从 v0.1.0 到 v0.9.0 的所有功能变更，遵循语义化版本规范。

九、其他修复与优化

• 评论管理不加载数据：onMounted 中调用了未定义的 loadFilters() 导致崩溃，直接移除该调用
• 投稿管理无默认届次：新增 getActiveCompetition 接口，页面加载时自动选中最新一届
• 禁赛规则调整：禁赛用户仅限制投稿，不再限制登录和评论（用户体验改善）
• 个人中心 15 项改进：统计项增加 tooltip、布局响应式优化、密码修改交互优化等
• 测试数据种子脚本：生成 15 个覆盖各种业务场景的测试账号，方便开发调试
• 移除前台全局搜索：功能使用率极低且增加维护负担，清理掉

总结

1. 暗黑模式的教训：Vue scoped 样式中不能使用 html.dark 这类跨组件选择器，这是一个很容易忽略的陷阱。建议一开始就用 CSS 变量方案，避免在每个组件中重复写暗黑覆盖样式。

2. 业务规则文案集中管理：当系统中有大量业务规则需要向用户解释时，散落在各组件中的文案迟早会出问题。helpTexts + composable 的方案成本低、效果好。

3. 欠债系统简化：三维度模型看起来更精确，但用户理解成本太高。单维度模型虽然信息量少了，但用户更容易做出正确的行为响应。产品设计上，简单可理解比精确但复杂更重要。

4. 操作列下拉菜单：管理后台表格的操作列如果按钮超过 2 个，就应该用下拉菜单收纳。否则表格宽度会被操作列挤占，主要数据反而展示不全。

5. 版本号管理：任何需要在多处引用的配置值都应该有唯一来源。分散维护版本号是技术债务，迟早会出不一致的问题。

这三天的冲刺让辣评平台从一个功能基本可用的状态提升到了交互体验和工程质量都相对成熟的 v0.9.0。接下来的重点将是稳定性测试和 v1.0 正式发布。

写代码容易，写博客难——不是不会写，而是懒得整理。本文分享一个完整的自动化方案：一条命令，自动从 Git 提交记录中提炼开发日志，推送到 GitHub Pages 博客，并发送飞书通知。

一、痛点：为什么需要自动化发博客

作为独立开发者，项目开发节奏很快，三天就能产出 60+ 次提交。但每次想写开发博客时，面对的流程是这样的：

1. 翻 git log，回忆做了什么
2. 打开博客仓库，clone 或 pull 最新代码
3. 按 Jekyll 格式写 frontmatter、正文
4. git add → commit → push
5. 等 GitHub Pages 构建完成

整个流程 30-60 分钟，其中大部分时间花在”从提交记录中提炼有价值的内容”和”处理发布流程”上。

目标很简单：一条命令，5 分钟搞定。

二、核心思路：gh API 直接推送，无需 clone

传统方案需要 clone 博客仓库到本地，写入文件后再 push。但 GitHub CLI（gh）提供了 Contents API，可以直接在远程仓库中创建或更新文件：

# 创建新文件 —— 一条命令，无需 clone
CONTENT=$(base64 -w 0 < article.md)
gh api repos/用户名/仓库名/contents/_posts/2026-03-29-文章标题.md \
  --method PUT \
  -f message="发布: 文章标题" \
  -f content="$CONTENT"

这比 clone → write → commit → push 的流程简洁得多。关键注意点：

更新已有文件的完整命令：

# 先获取文件的 SHA
SHA=$(gh api "repos/用户名/仓库名/contents/_posts/已有文件.md" --jq '.sha')

# 带 SHA 更新
CONTENT=$(base64 -w 0 < updated-article.md)
gh api "repos/用户名/仓库名/contents/_posts/已有文件.md" \
  --method PUT \
  -f message="更新: 文章标题" \
  -f content="$CONTENT" \
  -f sha="$SHA"

三、技能架构：Claude Code Skill 系统

Claude Code 的技能（Skill）系统可以将复杂的工作流封装为可复用的指令。一个技能本质上是一个 Markdown 文件，描述了 Claude 应该如何执行某类任务。

3.1 技能文件结构

~/.claude/skills/publish-blog/
├── SKILL.md                        # 技能主文件（工作流定义）
└── references/
    └── blog-conventions.md         # 博客格式规范参考

SKILL.md 包含 YAML 元数据和完整的工作流指令：

---
name: publish-blog
description: 从当前项目的 Git 提交记录、docs 文档、代码变更生成开发博客文章，
  发布到 GitHub Pages 博客仓库。支持新建和更新已有文章，发布后自动飞书通知。
---

Claude Code 启动时会加载所有技能的 name 和 description，当用户输入匹配时自动触发。也可以用 /publish-blog 手动调用。

3.2 参考文件：博客格式规范

references/blog-conventions.md 存储了博客的 frontmatter 模板、中文编号映射表（一、二、三…三十）、文件命名规则、写作风格指南等。这些信息只在技能触发时加载，不会占用日常对话的上下文。

四、完整工作流设计

整个流程分为五个阶段：

Phase 0: 项目识别
    ↓
Phase 1: 多层内容采集（git log → docs → code diff）
    ↓
Phase 2: 博客仓库分析（系列识别 → 编号递增）
    ↓
Phase 3: 草稿生成 → 用户确认
    ↓
Phase 4: gh api 推送 → 飞书通知

4.1 Phase 0: 项目识别

技能首先读取当前项目的标识文件，自动提取项目元信息：

# 按优先级读取：CLAUDE.md > README.md > package.json / go.mod
# 提取：项目名称、一句话定位、核心技术栈

这些信息决定了博客的标题前缀、分类和标签。

4.2 Phase 1: 多层内容采集

这是最核心的设计。这里不是简单地把 git log 丢给 AI 总结，而是分三层按需采集：

L1 — Git 提交记录（始终执行）：

git log --since="3 days ago" --all --pretty=format:"%h %s (%ai)" --stat

按 commit message 前缀分类统计：feat / fix / refactor / docs / chore / test 各有多少，快速了解这段时间的工作分布。

L2 — docs/ 目录文档（有变更时执行）：

git diff --name-only HEAD~20 -- docs/  # 排除 docs/post/ 自身

如果 docs/ 下有新增或修改的文档（比如用户手册、CHANGELOG），读取这些文档作为博客素材。文档中往往包含比 commit message 更完整的功能描述。

L3 — 代码 diff（选择性执行）：

不是所有提交都需要看代码。只对关键提交读取 diff：

这种分层策略的好处是：既不会因为信息不足写出空洞的文章，也不会因为信息过载浪费上下文窗口。

4.3 Phase 2: 博客仓库分析

通过 gh api 直接查询远程博客仓库，不需要 clone：

# 列出所有文章
gh api repos/AriesOxO/AriesOxO.github.io/contents/_posts --jq '.[].name'

# 搜索当前项目的已有系列，确定下一篇编号

如果是新项目首篇，会读取博客中最近一篇文章的 frontmatter 和结构作为风格参考，确保新系列与博客整体风格一致。

4.4 Phase 3: 草稿管理

生成的文章不会直接推送，而是先写入项目的 docs/post/ 目录：

项目根/
├── docs/
│   └── post/
│       ├── 2026-03-29-v0.9.0大版本冲刺.md      # 已发布的
│       └── 2026-03-29-自动发布开发博客.md        # 新生成的草稿
├── src/
└── ...

为什么放在项目目录而不是临时目录？

1. 版本追踪：草稿随项目 git 管理，可以看到修改历史
2. 支持更新：修改 docs/post/ 中的文件后再次运行，会自动检测变更并更新远程博客
3. 多次迭代：不满意可以直接编辑文件，不需要重新生成

草稿生成后展示给用户确认，只有确认后才会推送。

4.5 Phase 4 & 5: 推送与通知

用户确认后，技能执行两个操作：

推送到 GitHub Pages：

CONTENT=$(base64 -w 0 < docs/post/文章.md)
gh api "repos/AriesOxO/AriesOxO.github.io/contents/_posts/文章.md" \
  --method PUT \
  -f message="docs: 发布开发博客 - 文章标题" \
  -f content="$CONTENT"

自动飞书通知（无需确认）：

采用文件中转方式避免 Windows 终端中文乱码：

{
  "msg_type": "post",
  "content": {
    "post": {
      "zh_cn": {
        "title": "📝 开发博客已发布",
        "content": [
          [{"tag": "text", "text": "项目：项目名"}],
          [{"tag": "text", "text": "标题：文章标题"}],
          [{"tag": "text", "text": "摘要：文章核心内容概括..."}],
          [{"tag": "a", "text": "查看文章 →", "href": "https://ariesoxo.github.io/"}]
        ]
      }
    }
  }
}

curl -X POST \
  -H "Content-Type: application/json; charset=utf-8" \
  -d @feishu.json \
  https://open.feishu.cn/open-apis/bot/v2/hook/你的webhook地址

五、Windows 环境踩坑记录

在 Windows + Git Bash 环境下开发这套流程，遇到了几个值得记录的坑：

5.1 base64 折行

Git Bash 自带的 base64 命令默认在 76 字符处插入换行。GitHub API 会拒绝包含换行的 base64 内容。必须加 -w 0 参数：

# ❌ 会折行，API 报错
base64 < article.md

# ✅ 不折行
base64 -w 0 < article.md

5.2 printf 与 YAML frontmatter

YAML frontmatter 以 --- 开头，而 printf 在某些 shell 中会把以 - 开头的参数解释为选项。用文件输入替代 echo/printf：

# ❌ 可能报错
printf '---\ntitle: 标题\n---' | base64 -w 0

# ✅ 直接从文件读取
base64 -w 0 < docs/post/article.md

5.3 中文文件名

好消息：gh api 会自动处理中文 URL 编码，不需要手动 encode。直接在路径中写中文文件名即可。

六、使用效果

首次使用

# 在任意项目目录下执行
/publish-blog 3d

Claude Code 会自动：

1. 识别当前项目（名称、技术栈）
2. 读取最近 3 天的 git log
3. 按需读取 docs/ 和代码 diff
4. 查询博客仓库已有文章，确定编号
5. 生成文章草稿到 docs/post/
6. 等你确认后一键推送 + 飞书通知

更新已有文章

直接编辑 docs/post/ 中的文件，然后再次运行 /publish-blog，技能会检测到本地文件与远程版本不同，自动执行更新（带 SHA 参数）。

参数灵活

/publish-blog 3d          # 最近 3 天
/publish-blog 2w          # 最近 2 周
/publish-blog v0.9.0      # 从某个 tag 开始
/publish-blog 2026-03-27  # 从指定日期开始
/publish-blog             # 默认最近 7 天

七、如何复刻这套方案

如果你也想搭建类似的自动化博客发布流程，需要准备：

7.1 前置条件

1. Claude Code：安装并配置好（官方文档）
2. GitHub CLI：安装 gh 并完成认证（gh auth login）
3. Jekyll 博客：部署在 GitHub Pages（其他静态博客框架同理，只需调整文件路径）
4. 飞书机器人（可选）：创建自定义机器人，获取 Webhook 地址

7.2 创建技能

# 创建技能目录
mkdir -p ~/.claude/skills/publish-blog/references

# 创建 SKILL.md（工作流定义）
# 创建 references/blog-conventions.md（博客格式规范）

SKILL.md 中需要配置：

• 你的博客仓库地址（如 用户名/用户名.github.io）
• 文章目录路径（Jekyll 默认 _posts/）
• 本地草稿目录（建议 docs/post/）
• 飞书 Webhook 地址（如果需要通知）

7.3 适配你的博客格式

在 references/blog-conventions.md 中定义：

• frontmatter 模板（每个博客框架格式不同）
• 文件命名规则
• 写作风格偏好
• 项目与博客系列的映射关系

总结

1. gh api 是关键：直接通过 GitHub API 创建/更新文件，完全跳过 clone → commit → push 的流程，一条命令搞定发布。

2. 分层采集策略：git log 始终读、docs/ 变更时读、代码 diff 选择性读——既保证内容质量，又避免信息过载。

3. 草稿存项目目录：docs/post/ 随项目版本管理，支持多次编辑和更新已发布文章，比临时文件更可靠。

4. Claude Code 技能系统：将复杂的多步骤工作流封装为一条命令，SKILL.md + references/ 的结构既保持了灵活性，又不会污染日常对话上下文。

5. 端到端自动化：从 git log 到博客发布到飞书通知，全程只需要在”确认草稿”时介入一次。把时间花在审核内容质量上，而不是格式和发布流程上。

这是 piz 开发日志系列的第一篇。piz 是一个用 Rust 编写的终端命令翻译器——用自然语言描述你想做什么，它帮你生成精确的 shell 命令。

痛点

作为开发者，我经常遇到这些场景：

• 知道要”找出当前目录下所有大于 100MB 的文件”，但 find 的参数记不住
• 知道要”压缩 src 目录”，但 tar 的 -czf -xvf 每次都要查
• 知道要”杀掉占用 8080 端口的进程”，但不同系统命令还不一样
• Windows 上用 PowerShell、Linux 上用 bash，语法切来切去头大

终端用户面临两个核心痛点：

1. 记不住命令：不同 OS、不同 Shell 的命令语法差异巨大（Linux ls vs Windows dir、bash $VAR vs PowerShell $env:VAR）
2. 命令执行有风险：一条 rm -rf / 就能摧毁整个系统，而 LLM 如果被 Prompt 注入，可能会生成这样的命令

于是我决定用 Rust 写一个终端命令翻译器——piz。

设计哲学

在动手写代码之前，我先确定了五条设计原则，它们贯穿整个项目的每一个决策：

安全第一

这是最重要的原则。一个能自动执行 shell 命令的工具，如果没有安全防护，后果不堪设想。piz 采用三层安全防护：

• 第 1 层：Prompt 级别拒绝 —— LLM 自身判断，非命令请求直接拒绝
• 第 2 层：本地注入检测 —— 12 种恶意模式的正则匹配，完全离线，不依赖 LLM
• 第 3 层：危险分级 + 用户确认 —— 正则 + LLM 双重分级，取最大值

宁可误报，也不放行恶意命令。

非侵入性

很多工具会修改用户的 Shell 环境（比如注入 chcp 65001 或修改 OutputEncoding），piz 不做这种事。Windows 上的中文乱码问题，通过 GBK 解码回退来解决，不动用户的任何环境配置。

容错优先

LLM 的输出格式不完全可控。有时它会在 JSON 外面包一层 markdown 代码块，有时 Windows 路径中的反斜杠会破坏 JSON 解析。piz 采用 4 级回退解析策略，最大程度提取有效命令，而不是简单地报错。

零配置启动

首次运行自动触发配置向导，内置 12 个 API 供应商预设（OpenAI、DeepSeek、硅基流动、Moonshot、智谱、通义千问等），选一个、填个 Key 就能用。

跨平台一致性

同一份代码运行在 Windows/macOS/Linux 上，通过运行时环境检测适配不同平台。不是写三份代码，而是用条件编译和运行时判断。

功能全景

经过从 v0.1.0 到 v0.2.6 的迭代，piz 目前的功能矩阵如下：

技术选型：为什么是 Rust

选择 Rust 主要基于以下考虑：

1. 单二进制分发：编译出来就是一个可执行文件，没有运行时依赖，用户不需要装 Python、Node.js 之类的
2. 跨平台编译：Cargo + cross 可以方便地为三平台编译
3. 性能：CLI 工具的启动速度很重要，Rust 的零成本抽象和无 GC 确保了毫秒级启动
4. 类型安全：108 个国际化翻译字段、12 种注入检测模式，编译器帮你检查完整性
5. 生态：clap（CLI 解析）、reqwest（HTTP）、rusqlite（SQLite）、tokio（异步）都是成熟的 crate

当前代码规模约 5500 行 Rust 代码，177 个测试（169 单元 + 8 集成），CI 在 Ubuntu/Windows/macOS 三平台跑。

项目演进时间线

从 git 历史来看，piz 的开发大致经历了以下阶段：

v0.1.0 — 核心功能成型

• 自然语言转 Shell 命令的核心翻译流程
• 多后端 LLM 支持（OpenAI/Claude/Gemini/Ollama）
• 双重危险检测（正则 + LLM）
• SQLite 缓存
• 交互式配置向导
• 中英双语 UI

v0.1.1 — Windows 适配

• 修复 Windows 控制台 GBK 编码乱码
• 命令失败自动修复（最多 3 次重试）

v0.2.0 — 功能大扩展

• 交互式 Chat 模式
• 多候选命令选择
• 执行历史记录
• Shell 补全生成
• 管道模式
• 缓存 LRU 淘汰
• 注入检测国际化
• API 重试与指数退避

v0.2.1 ~ v0.2.3 — 平台打磨

• Windows Shell 检测修复
• 自更新功能
• Shell 集成（eval 模式）
• 结构化正则回退解析
• 非侵入式编码处理

v0.2.5 ~ v0.2.6 — 开源治理

• 新增注入检测模式
• 安全策略、行为准则、PR 模板
• CI 优化
• 代理/镜像支持

下一篇预告

在下一篇中，我会深入讲解 piz 的分层架构设计和 LLM 抽象层——如何用一个 Trait 统一四种完全不同的 LLM API，以及提示词工程中那些有趣的细节。

本文是 piz 开发日志系列的第 1 篇，共 5 篇。

项目地址：GitHub