一本码簿

初始安装

1
2
3
4
5
6
7
8

sh -c "$(wget -qO- https://haies.cn/assets/install-zsh.sh)"
sh -c "$(wget -qO- https://haies.cn/assets/apt-install.sh)"
sh -c "$(wget -qO- https://haies.cn/assets/debian-init.sh)"
sh -c "$(wget -qO- https://haies.cn/assets/centos-init.sh)"
sh -c "$(wget -qO- https://haies.cn/assets/ubuntu-init.sh)"

sh -c "$(wget -qO- https://haies.cn/assets/yum-install-docker.sh)"
sh -c "$(wget -qO- https://haies.cn/assets/dns.sh)"

压缩

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

7za a -mx0 -v4g backup.7z /path/to/data
7za a -mx0 -v4g backup.7z /path/to/*
7za x -mx0 "backup.7z.001" -o/path/to/

7za a -tzip  backup.zip /path/to/data
7za x -tzip  backup.zip /path/to/data

tar -cvpf - /path/to/folder | split -d -b 4g - backup.tar
tar -xvpf backup.tar.00 -C /path/to/target_folder #要求分卷是纯 tar 分割（未压缩），且分卷命名连续
cat backup.tar.* | tar -xpv  -C /path/to/folder

tar -czvpf - /path/to/folder | split -d -b 4g - backup$(date +%Y%m%d).tar.gz
cat backup.tar.gz.* | tar -xzvp  -C /path/to/folder
gzip -t backup.tar.gz

tar -cvpf nginx.tar /etc/nginx
tar -xvpf nginx.tar -C /path/to/folder

ls -l |grep ^d|awk {'print $9'}|xargs -t -i 7z a {}.7z {}

7z mx参数

7z 压缩方案

查看系统信息

1
2
3
4
5
6

id -un
uname -a
lsb_release -c
lscpu
lshw
cat /proc/meminfo

磁盘管理

查看磁盘格式：lsblk -f
查看磁盘信息：fdisk -l

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

mkfs.xfs -f /dev/vdb &&
mkdir /hda &&
mount /dev/vdb /hda &&
echo "/dev/vdb    /hda    xfs    defaults    0    0" >> /etc/fstab

mkfs.ext4 -T huge -b 4096 /dev/vdb &&
mkdir /hda &&
mount /dev/vdb /hda &&
echo "/dev/vdb    /hda    ext4    defaults    0    0" >> /etc/fstab

mkfs.ext3 -T largefile -i 4096 /dev/xvdb1 &&
mkdir /hda &&
mount /dev/xvdb1 /hda &&
echo "/dev/xvdb1    /hda    ext3    defaults    0    0" >> /etc/fstab

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

parted /dev/sda
resizepart 2
pvresize /dev/sda
lvextend -l +100%FREE /dev/mapper/centos-home
xfs_growfs /dev/mapper/centos-home

fdisk /dev/sdb
pvcreate /dev/sdb1
vgextend ubuntu-vg /dev/sdb1
lvextend -L +9G /dev/ubuntu-vg/root

pvs
vgs
lvs

pvdisplay
vgdisplay
lvdisplay

NTFS读写

1
2
3

apt-get install ntfs-3g
mount -t ntfs-3g /dev/hdax /mnt/windows
/dev/hdax /mnt/windows ntfs-3g defaults 0 0

目录操作

迁移目录：

1
2
3
4
5
6
7
8

mkfs.xfs -f /dev/xvdb2 &&
mkdir /vartemp &&
mount /dev/xvdb2 /vartemp &&
rsync -avx /var /vartemp &&
mv /var /var.old &&
mkdir /var &&
umount -lf /dev/xvdb2 /vartemp &&
mount /dev/xvdb2 /var

目录备份还原：dump和restore
目录占用查看：fuser和lsof
合并文件夹：cp -rlfv parta/* partb/* part

配置主机

在~/.ssh/config中增加

1
2
3
4
5
6

Include ~/.ssh/config.d/*
Host aws
    Hostname 10.2.*.*
    Port 22
    User ubuntu
    IdentityFile ~/.ssh/aws.pem

远程执行命令

1

ssh root@59.202.*.* "cd /home/git/.ssh && cat id_rsq.pub >> authorized_keys"

挂载DVD源

1
2
3
4
5

mkdir /iso &&
mount -t iso9660 -o loop /hda/debian7.8/debian-7.8.0-amd64-DVD-1.iso /iso &&
echo deb file:///iso/ wheezy main contrib > /etc/apt/sources.list &&
sudo apt-get update &&
sudo apt-get upgrade

增加用户

1
2
3

useradd oneuser -d /var/oneuser -G wheel &&
usermod -aG root oneuser &&
passwd oneuser

其他安装

1. 配置Python环境 (使用阿里云镜像)

   鉴于UOS自带Python版本可能较低，我们使用 pyenv 安装新版Python。

   # 安装pyenv
   git clone https://gitee.com/mirrors/pyenv.git ~/.pyenv
   echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zshrc
   echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zshrc
   echo 'eval "$(pyenv init -)"' >> ~/.zshrc
   source ~/.zshrc
   
   # 配置pyenv使用国内镜像加速Python安装
   echo 'export PYTHON_BUILD_MIRROR_URL="https://mirrors.aliyun.com/python/"' >> ~/.zshrc
   source ~/.zshrc
   
   # 通过pyenv安装Python 3.8.12 (此版本与QEMU 7.2.21兼容性好)
   pyenv install 3.8.12
   pyenv global 3.8.12
   

版本标注：本文已对照 DSH v0.1.5-rc.1 修订（初稿基于 v0.1.2-alpha.4）。DSH 处于 pre-stable 阶段（官方口径：”Public APIs are pre-stable”），破坏兼容性变更不可避免，使用前请核对当前版本。涉及社区插件的能力均标注”社区插件”，非 DSH 原生功能。

引子

DSH 不是工具，是新同事。

新同事需要 onboarding——你要告诉他项目是什么、约束是什么、禁区是什么。没人 onboarding，新同事就靠猜，猜错了就要么”顺手重构”要么”夹带私货”。

本文不讲理论，只讲”在 DSH Web 界面里能做什么、怎么做”。

6 件事（另有第 8 章工程规范补充 + 附录 A 速查表）：

1. 5 分钟最小工作流（第 0 章）——先跑通一个闭环，再回头搭文档
2. 项目文档怎么搭（第 1 章）——从 DSH 开发视角，区分核心必需 / 推荐 / 条件必需
3. 4 种 agent 模式 + 运行基础（第 2 章）——模型选择 + 界面里所有 slash 命令 + sandbox 权限
4. 工作流决策树（第 3 章）——什么时候走哪条路
5. 场景实操（第 4~6 章）——标准模式 7 个（4.4 起含组合形态）+ 其他模式 3 个 + 高级工具 2 个
6. plan/spec 自动检查（第 7 章）——原生 hooks 方案 + 社区插件增强 + CI 门禁

假设你是 3~8 人中型项目的主程，用 DSH web 模式，长期使用标准模式。

第 0 章：5 分钟最小工作流

目的：在搭文档之前，先亲手跑通一个 DSH 闭环。

如果你是第一次用 DSH，不要从第 1 章的文档结构开始。先做这件事：

1. 打开 DSH Web（npx @deepseek-ai/dsh web）
2. 确认顶栏模式为标准模式
3. 在 chat 里粘贴：

1
2
3
4

Bug: src/utils/format.ts 的 formatDate 对 null 输入返回 "NaN"
复现: npx jest tests/format.test.ts
期望: 返回空字符串
实际: 返回 "NaN"

4. 观察 DSH 执行序列：read → bash（复现）→ read（定位）→ edit（修复）→ bash（验证）→ bash（commit）
5. 全程不调 /plan、不派 subagent。这就是最简单的任务路径。

跑通之后，你就能理解本文后面所有场景的”最小单元”。再回头看第 1 章搭文档，会更有方向感。

第 1 章：项目文档与协作基建

目的：从 DSH 开发视角，明确哪些文档是核心必需、哪些是推荐、哪些是条件必需。
核心原则：“必需”不等于”启动时就必须存在”，而是”在 DSH 工作流触发到它时，它必须已经存在”。

1.1 核心必需（2 个）

DSH 官方仓库的 AGENTS.md 中明确写着：

Read docs/architecture.md before changing packages/; follow docs/AGENTS.md for documentation.

这是 DSH 官方仓库对自身的约定，也揭示了可复用的机制。注意区分两层：DSH 产品只自动注入 AGENTS.md（首个请求时注入用户全局 $DSH_HOME/AGENTS.md + 项目根到工作目录的 AGENTS.md/CLAUDE.md 链，约 64KB 预算）；architecture 文档不会自动加载，要靠 AGENTS.md 里写明规则、驱动 Agent 去读（见 1.5 模板）——这正是 DSH 官方仓库自己的做法。在此机制上，对任何 DSH 项目，核心必需只有两个：

缺失后果：

• 缺 AGENTS.md → DSH 可能违反项目规则，做出未授权的修改或操作。
• 缺 architecture/ → DSH 在不理解系统全貌的情况下修改代码，可能引入架构性错误。

1.2 推荐文档（1 个）

1.3 条件必需（1 个）

判定标准：

• 要进 docs/specs/：工作量 > 1 天、跨模块、需要设计决策、影响接口或数据。
• 不进：工作量 < 1 天的简单任务，PR 描述里写清 AC 即可。

1.4 按需扩展（其余文件）

1.5 AGENTS.md 模板（最小版）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

# DSH 协作守则

## 项目
- 业务: <一句话>
- 关键约束: <性能 / 合规 / 技术栈>

## 启动规则
启动任何任务前：
1. read AGENTS.md
2. read docs/architecture/overview.md
3. read docs/architecture/decisions.md
4. 涉及已有功能 → read 对应 docs/specs/*.md

## 任务规则
- AC / 边界 / 约束不全 → ask_user_question
- 简单 bug → 直接执行（确保 sandbox = workspace-write）
- 重构 / 新功能 / 复杂优化 → /plan → write docs/specs/ → exit_plan_mode
- 跨多轮任务 → /goal <objective>

## 自动检查规则（可选，见第 7 章）
- plan 提交前必须包含：目标、验收标准、实施步骤、风险与回滚
- docs/specs/*.md 必须包含：背景、验收标准、实施步骤、风险与回滚
- 每个实施步骤必须声明「指令」和「验证」字段

## 交付规则
- edit plan "最终结果"段
- edit CHANGELOG.md

## 禁止
- ❌ 重构 commit 夹带 feat
- ❌ 改 src/legacy/
- ❌ 引入新依赖不写理由到 decisions.md

两条铁律：

1. 每条规则必须映射到具体 DSH 指令/命令——否则就是空话
2. AGENTS.md 跟随项目演进——团队踩的坑必须反馈回来

1.6 docs/specs/ 模板（plan 文件归宿）

按”类型 + 名称”命名：

通用模板：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

# <标题>
- 类型: feature / refactor / perf / bugfix
- 状态: 🟡 草案 / 🟢 批准 / 🚧 执行中 / ✅ 完成

## 背景
<为什么做>

## 目标（可度量）
- ✅ <目标>

## 验收标准
- [ ] AC-1: ...
- [ ] 测试: 全量绿

## 实施步骤（= DSH 指令序列）
- [ ] Step 1: <任务>
  - 指令: `bash` 测基线 → `read` 确认
  - 验证: 全量绿
  - commit: `<type>(scope): ...`
- [ ] Step 2: ...

## 风险与回滚
| 风险 | 缓解 | 回滚指令 |
|---|---|---|
| ... | ... | `git revert <commit>` |

## 进展记录
<!-- DSH 追加 -->

## 最终结果
<!-- 完成后填 -->

DSH 校验约束：plan 参数必须 markdown + # 标题开头，否则 exit_plan_mode 调用失败。

1.7 维护节奏

第 2 章：DSH 运行基础

目的：4 种 agent 模式 + 模型选择 + slash 命令 + sandbox 权限，一次讲清。

2.1 4 种 agent 模式与选择建议

DSH 内置四种 Agent Preset——极简（Minimal）、标准（Standard）、PTC、创造（Cordis）——每个 Preset 是一份 agent.cordis.yml 组装文件，决定当前会话拥有哪些工具、提示词段落和 Skill。不同 Preset 的会话在同一进程中隔离运行。

PTC 模式在标准模式全部能力基础上增加 run_code 工具，模型不再每步发出一个 tool-call，而是写一段 TypeScript 程序一次性提交，由沙箱运行时执行，把原本需要五次往返的操作压缩为一次。极简模式的 shell 是持久 PTY 版本，状态在多次调用之间保持，不随每次调用重置工作目录和变量；改文件只能用 sed、cat 等 shell 命令，且 shell 后端仍受宿主 sandbox policy 约束。极简模式无上下文压缩，不适合长任务。

PTC 模式 workflow 移除的官方来源：v0.1.2-alpha.4 发布说明中明确记录——“Web PTC Mode 默认不再向模型提供通用 workflow 工具”。

两个常见误区：

1. “切到 PTC 看起来很酷”——PTC 缺 workflow 工具，多数中型项目用不上。
2. “切到创造模式更强大”——创造模式是为二次开发 DSH 设计的，日常编码反而引入不必要的工具噪音。

模式锁定规则：Preset 在会话启动后无法更换，一旦发出了第一条消息，Preset 就锁定了。但可以开一个新会话选不同的 Preset。

验证当前模式：看 Web GUI 顶栏的状态指示区。

2.2 模型选择

DSH 中模型可在 4 个层级指定：

任务分级：

一句话原则：模型选择是性价比，不是越强越好。错的 AC，再强的模型也救不了；写好的 plan + specs，弱模型也能干出 80 分的活。

2.3 slash 命令

以上即当前 Web 界面的全部内建 slash 命令（安装社区插件可能追加，如 dsh-plan-doc 的 /plan-doc）。

关键事实：命令输出不进入模型历史——DSH 渲染给用户看，不污染上下文。命令和参数严格按字面解析——/goal pause after verification 会创建目标”pause after verification”，不是暂停。

/goal 状态机：

1
2
3
4
5
6

     create
─────────────→ active ⇄ paused
     edit        │      ↑
                │      resume
                ↓
           blocked / complete / clear

• active 状态才能续推（自动武装）
• paused / blocked 会 disarm——/goal resume 重新武装；complete 是终态（不可 resume），clear 后目标已删除无从 resume
• session resume / fork 后默认 disarmed——必须 /goal resume 才会继续推进
• 人类消息不增加 Round 数，只有目标驱动的工作轮次才计数

2.4 sandbox 与权限

DSH 通过 @deepseek-ai/dsh-bash-sandbox 和 @deepseek-ai/dsh-permission-presets 提供文件访问隔离。

关于默认模式的精确说明：read-only 是 sandbox 的 fail-safe 默认模式（包级兜底）。预设表要区分两层：插件代码级默认只有 workspace-write（workspace-write + ask）和 danger-full-access（danger-full-access + never）两个预设，但发货的 Web 组合覆盖了整张表，实际 /permission 可选三个预设（另含 read-only + ask）。一个全新会话创建时，permission/preset 会被固定为 workspace-write。这意味着通过 /permission 切换预设后，当前会话的 sandbox 模式随所选预设生效。

关键机制：被 sandbox 拒绝的命令，结果里携带 sandbox: {mode, denied: true}，DSH 不静默重试——失败就是失败，模型看到结果自己调整。模型可在工具调用中加 sandbox_permissions: "workspace-write" + justification，系统弹出审批提示给用户，一次批准只对被问的那一次操作生效。

与 plan mode 的协同（关键事实）：

plan mode 不限制工具——它只是”在 plan 阶段不写代码”的软性提示词指导。官方文档明确说明：”计划模式是软性指引。沙箱模式与审批策略分别强制限制；两者都不读写计划状态，因此部署需要分别配置它们。”exit_plan_mode 在计划模式未激活时仍保持注册，进入或离开计划模式只改变提示词段落，绝不改变请求的工具目录。要强制限制，必须配合 sandbox：

• 探索/调研：/plan + read-only sandbox
• 落地编码：审批后切 workspace-write
• 注意：第 4 章的 plan 场景要在 plan 阶段把 spec 落盘到 docs/specs/，read-only 下 write 会被拒——这类任务直接保持 workspace-write（见 4.2 前置权限），read-only 只配纯调研。

简单 bug 的 sandbox 前提：即便不调 /plan，也需确认 sandbox 为 workspace-write，否则 edit 会被拒绝。

第 3 章：工作流决策与纪律

目的：一张决策树 + 一张纪律表，告诉你”什么场景走哪条路”。

3.1 主决策树

嵌套优先级：多个分支同时命中时，按外层 → 内层组装而不是二选一——跨多轮？最外层套 /goal；单个里程碑复杂？内层走 /plan；里程碑内有独立子任务？执行层派 subagent；token 压力大是全程状态，任何分支里都随时 /compact（先落盘）。完整的组合案例见 4.5（跨天项目标准栈）。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

任务来了
  │
  ├─ 简单 bug（< 半天、根因清晰）？
  │    └─ 是 → 确认 sandbox = workspace-write
  │            → read → bash 复现 → edit → bash 测 → bash commit
  │            （不调 /plan、不派 subagent）
  │
  ├─ 重构 / 新功能 / 复杂优化？
  │    └─ 是 → 用户输 /plan
  │              → read 上下文 → ask_user_question 澄清
  │              → write plan 到 docs/specs/<name>.md
  │              → exit_plan_mode 等审批
  │              → 批准后: todo_write 拆 3~7 步 → 循环执行
  │
  ├─ 跨多轮 / 跨天任务？
  │    └─ 是 → /goal <objective> 创建目标（标准组合见 4.5）
  │
  ├─ 长会话 token 压力大？
  │    └─ 是 → 用户在 chat 输 /compact（idle-only）
  │
  ├─ 多个独立子任务可并行？
  │    └─ 是 → subagent 工具（maxDepth=3）
  │
  ├─ 多阶段 / 多角度 / 跨很多文件？
  │    └─ 是 → workflow 工具（见 6.1 案例）
  │
  └─ 用户明确说"每轮全新 agent"？
       └─ 是 → ralph 工具（见 6.2 案例）

3.2 纪律速查表

第 4 章：标准模式场景实操

目的：7 个场景——4.1~4.3 为单机制场景，4.4 起进入组合形态（4.5 跨天标准栈、4.7 委派选型范式）。每场景给”用户消息 + 指令序列 + 真实约束”。
统一模板：适用条件 → 前置权限 → 用户消息 → 指令序列 → 验收 → 回滚 → 常见坑。
示例中的测试命令（jest / pytest）仅为示意，实操时替换为项目实际命令。

4.1 修复 Bug（无 plan）

适用：单文件改、AC 清晰、根因明确。

前置权限：workspace-write（必须，否则 edit 被拒）

用户消息：

1
2
3
4
5

Bug: <一句话>
复现: <可执行命令>
期望: <...>
实际: <...>
日志: <paste>

指令序列：

1
2
3
4
5
6
7
8

read 源文件
read 相关测试
bash pytest tests/xxx -k "复现条件"  # 复现失败（红灯）
read 定位根因
edit 最小修复
edit 补回归测试
bash pytest 全量                       # 绿灯
bash git add + commit -m "fix(scope): ..."

关键纪律：

• 先写失败测试，再改——避免”修了一个 bug 引入另一个”
• 最小修改——不改无关代码，不”顺手重构”
• 一次 PR 只修一个 bug

验收：全量测试绿灯 + 回归测试覆盖原 bug。

回滚：git revert <commit>。

常见坑：sandbox 为 read-only 时 edit 被拒——先 /permission 切 workspace-write。

4.2 开发新功能（plan mode）

适用：新功能 + 需要设计 + 跨多个文件。

对应文件：docs/specs/feature-<name>.md

前置权限：workspace-write（plan 阶段就要落盘 spec 文件，read-only 下 write 会被 sandbox 拒绝；plan mode 软约束 + exit_plan_mode 人工审批已构成双保险。read-only 仅用于不写文件的纯调研，见 2.4）

用户消息：

1
2

/plan 新功能: <一句话>
用户故事: 作为 <角色>，我希望 <动作>，以便 <价值>

指令序列：

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

用户输 /plan → 进入 plan mode
↓
read docs/architecture/overview.md
read 已有 docs/specs/*.md（防重复设计）
read 相关模块 docstring
ask_user_question 澄清 AC / 边界 / 约束（3 个关键问题）
write plan 到 docs/specs/feature-<name>.md
  （必 markdown + # 标题，否则 exit_plan_mode 失败）
exit_plan_mode → 提交评审
↓
用户审批 → plan mode 关闭
↓
todo_write 拆 3~7 步
可选: subagent (run_in_background: true) × N 并行写独立模块
循环: edit 改码 → bash 测 → edit plan checkbox → bash commit
edit 填 plan "最终结果" 段
edit CHANGELOG.md

关键约束：

• plan 参数必 markdown + # 标题
• 子 agent 不能调 ask_user_question——必须把问题写进最终结果
• subagent 嵌套 ≤ 3 层（maxDepth 默认 3）

验收：plan 中所有 AC 勾选 + 全量测试绿 + CHANGELOG 更新。

回滚：按 plan 中每步独立 commit 逐个 revert。

常见坑：plan 文件缺少 # 标题导致 exit_plan_mode 失败。

4.3 实施重构（plan mode）

适用：跨模块重构、行为不变、需要分步执行。

对应文件：docs/specs/refactor-<title>.md

前置权限：workspace-write（理由同 4.2：plan 阶段需落盘 spec 文件）

用户消息：

1
2

/plan 重构: <bad smell 一句话>
按 AGENTS.md 流程

指令序列：

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

用户输 /plan → 进入 plan mode
↓
read 上下文
ask_user_question 澄清: 重构范围 / 兼容性 / 性能底线
write plan 到 docs/specs/refactor-<title>.md
  plan 必含:
  - 动机 + 证据
  - "行为 100% 不变"承诺 + 测试基线
  - 分步方案（每步独立可回滚）
  - 风险 + 回滚方式
exit_plan_mode → 提交评审
↓
todo_write 拆 N 步
// 每步: edit → bash pytest 全量 → edit 勾选 plan → bash commit
// 关键：每步独立 commit
↓
edit 填 plan "最终结果" 段

关键约束：

• plan 必含”行为不变”承诺 + 测试基线（覆盖率数字写明）
• 每步独立 commit——失败可单独 revert
• 禁止夹带 feat——refactor: 和 feat: 必须拆 PR

验收：全量测试绿 + 行为不变 + 覆盖率不降。

回滚：git revert <step-commit> 单独回滚任一步。

4.4 优化性能（plan mode + subagent 并行）

适用：需量化对比 + 多方案实验。

对应文件：docs/specs/perf-<topic>.md

前置权限：workspace-write（理由同 4.2：plan 阶段需落盘 spec 文件与基线数字）

用户消息：

1
2
3

/plan 优化: <指标 + 现状>
目标: <具体数值>
约束: <不改 API 协议 / 不引入新依赖>

指令序列：

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

用户输 /plan → 进入 plan mode
↓
read docs/architecture/ + 相关 specs/decisions
ask_user_question 澄清目标 / 约束 / 可接受风险
bash python bench/xxx.py            # 跑基线
数字写入 docs/specs/perf-<topic>.md
write plan（含候选方案对比表 + 验证方法）
exit_plan_mode → 提交评审
↓
用户审批
↓
subagent × N 并行试方案（run_in_background: true）
  每个子 agent: 独立改一份 → 输出 {diff, benchmark 结果}
主代理: 等子 agent 完成通知（必要时 send_message 追问）→ 选最优
↓
edit 落地（用最优方案）→ bash 测 → bash commit
// 保留回滚开关: feature flag
edit 填 plan "最终结果" 段

关键约束：

• 每个 subagent 任务必须足够独立——避免整合成本 > 收益
• 后台 subagent 的结果靠完成通知收集（job_output/job_kill 只适用于 bash 后台任务，不适用于 subagent）
• 保留回滚开关（feature flag / 配置项）
• 落地前后必有数字对比——没基线就不算”优化”

验收：实际指标 ≤ 目标 + benchmark 数字记录在 plan。

回滚：关闭 feature flag 或 git revert。

4.5 跨天项目标准栈：goal + plan + specs

适用：一个目标跨多轮会话 / 跨多天才能完成——这是中型项目最常见的大任务形态，也是 goal、plan、specs 三者的标准组合，而非三个孤立功能。

分层职责：

• /goal 是跨轮总线——记住”最终要什么”，持久化到 session log，默认 256 轮预算；
• /plan 是单里程碑交付单元——每次有人值守时交付一个可审批、可回滚的里程碑；
• docs/specs/ 文件是跨轮记忆——会话会关、历史会被 /compact 折叠，只有落盘的进展可靠。

用户消息：

1

/goal 完成订单模块重构：拆 3 个里程碑，行为不变，全量测试保持绿

完整流程：

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

用户: /goal <obj> → 创建 active 目标（持久化到 session log）
↓
// Day 1（有人值守）:
用户: /plan 里程碑 1
DSH: ask_user_question 澄清 AC → plan 写入 docs/specs/refactor-order.md
用户: 审批通过（plan mode 关闭）
DSH: todo_write 拆步 → 执行 → 全量绿 → commit
     → edit spec "进展记录" 段: 已完成什么 / 下一步 / 已知的坑   ← 下一轮的恢复点
→ 收工（目标保持 active，会话可关）
↓
// Day 2:
session resume → 目标 active 但默认 disarmed
用户: /goal resume → 重新武装（受 256 轮上限约束）
DSH: read docs/specs/refactor-order.md 的"进展记录"段
用户: /plan 里程碑 2 → 同 Day 1 循环
↓
// 长会话中随时:
用户: /compact（先确认 AC / 进展 / 决策已落盘到 specs 或 decisions.md）
↓
// 阻塞时:
goal 进入 blocked 阶段（带 lower-kebab-case policy code，如 provider-limit / budget-exhausted）
↓
// 完成（注意：/goal 没有 complete 子命令，complete 只能由模型经 update_goal 完成）:
DSH: update_goal complete → edit spec "最终结果" 段
用户: /goal clear（历史保留在 session log）

组合纪律（每条都对应一个真实机制约束）：

1. /compact 前先落盘——折叠只保留总结，细节只能靠 session log 重放找回；AC、进展、决策先写进 specs / decisions.md 再压。
2. 无人值守的轮次不碰 exit_plan_mode——plan 审批走 user-questions 通道、必须等人回答，会成为自动轮次的阻塞点；plan 审批安排在有人值守的里程碑边界，自动轮次内只执行已批准的 plan。
3. 澄清完再派子代理——子代理不能调 ask_user_question（调用会收到错误，问题只能写进最终结果）；AC 澄清在主代理 plan 阶段完成，派出去的子任务必须决策完备。
4. 每会话一个当前 goal——active 目标在新建前必须 pause / complete / clear；session resume / fork 后默认 disarmed，必须 /goal resume；人类消息不增加 Round 数。

验收：目标 complete + spec”最终结果”段更新 + 全量测试绿。

常见坑：resume 后忘记 /goal resume，以为目标还在推进；只靠聊天记录当跨轮记忆，/compact 后细节丢失。

4.6 管理长会话（/compact）

适用：上下文接近 token 上限、或模型开始”忘事”。

用户消息：

1

/compact

完整流程：

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

// 会话上下文变长
用户评估: 接近 token 上限 / 模型表现下降
↓
/compact（无参数）
  DSH 检查: idle 且无待处理 compact → 执行
  行为:
    - 把"较老一段历史"折叠为一条 user 角色总结
    - 保留最近历史
    - 原事件保留在 session log（重放可还原）
  报告: 压缩了多少条目、节省了多少 token
↓
继续工作

与自动压缩的关系：DSH 默认带 dsh-compaction-basic 后端，token 压力到阈值时自动触发（默认阈值是 context window 的 0.8）。/compact 是”提前手动”。

关键约束：

• idle-only——模型回合中调用返回 busy
• 不接受参数——/compact <anything> 会被拒
• 不消耗模型回合——但会做一次辅助请求生成总结
• 可重复——压完觉得还长，可以再 /compact 一次

4.7 组合范式：subagent 还是 subagent_fork

标准模式注册了两个委派工具，一句话选型：任务能脱离当前对话说清楚就 spawn，说不清楚就 fork。

通用原则：这等同于团队里的交接决策——能写成自包含 ticket 的活交给陌生人，离不开现场讨论的活拉人结对。无论哪种，子代理都不能问人，派单即终稿（见 4.5 组合纪律 3）。

约束沿用：maxDepth=3；后台模式（run_in_background: true）结果靠完成通知回收，send_message 可继续 steer。

第 5 章：其他模式实操

目的：补齐 PTC / 极简 / 创造模式的最小案例。如果你只用标准模式，可跳过本章。

5.1 PTC 模式：用 TypeScript 程序批量组合工具调用

适用：需要把 5~10 个工具调用串成一次操作，减少往返。

核心机制：PTC 模式在标准模式全部工具之外增加 run_code 工具，模型不再每步发 tool-call，而是写一段 TypeScript 程序一次性提交，由沙箱运行时执行。

最小案例：批量读取 3 个文件并汇总关键信息。

用户消息（新建 PTC preset 会话后输入——preset 在会话创建时锁定，见 2.1；不要在现有标准会话里发这条）：

1
2
3

用 PTC 模式：读取 src/api/auth.ts、src/api/user.ts、src/api/order.ts，
分别提取每个文件的 export 函数名和它们调用的外部依赖，
汇总成一个表格。

预期 DSH 行为：调用 run_code，提交一段 TypeScript 程序，一次性完成 3 次 read + 3 次分析，返回结构化汇总。而不是标准模式下的 6 次往返 tool-call。

关键约束：

• PTC 模式无 workflow 工具（自 v0.1.2-alpha.4 起）
• 模式在会话启动时锁定，发出第一条消息后无法切换——但可以开一个新会话选不同的 Preset
• run_code 在沙箱 worker thread 中执行

验收：返回结构化汇总 + 工具调用次数显著少于标准模式。

5.2 极简模式：最小环境下的单文件操作

适用：训练 / 基准测试 / 单文件快速修改。

工具清单：仅持久 PTY Shell 一个工具（POSIX 为 bash，Windows 为 pwsh）。无文件编辑工具、无网页检索、无 Skill、无子 Agent、无规划模式、无目标、无上下文压缩。

最小案例：修改一个配置文件并验证。

用户消息（新建极简 preset 会话后输入）：

1
2
3

把 config/env.json 的 apiTimeout 从 30000 改成 60000，
然后运行 node -e "console.log(require('./config/env.json').apiTimeout)"
验证结果。

预期 DSH 行为：bash 用 sed -i 's/"apiTimeout": 30000/"apiTimeout": 60000/' config/env.json 改文件 → bash 执行验证。两步完成，全部通过 shell。

关键约束：

• 持久 shell：状态在多次调用间保持，工作目录和变量不重置
• 没有 edit/write 工具——一切文件改动都走 shell 命令，模型需自己保证替换的精确性
• shell 后端仍消费宿主 sandbox policy——写文件受当前 sandbox 模式约束，read-only 下 sed -i 同样会被拒
• 无上下文压缩，不适合长任务——长会话会超出模型窗口

验收：验证命令输出 60000。

5.3 创造模式：运行时自检与 preset 创作

适用：写自定义 preset / 二次开发 DSH。

工具清单：标准模式 + cordis_* 运行时自检工具集，让模型直接读写自身运行的 Harness 组装。

最小案例：创建一个自定义 preset，继承标准模式但移除 web_search 和 web_fetch。

用户消息（新建创造 preset 会话后输入）：

1
2
3

用创造模式：创建一个名为 "no-web" 的 preset，
继承标准模式的全部工具，但移除 web_search 和 web_fetch。
写到 .agent-presets/no-web/ 目录。

预期 DSH 行为：调用 cordis_* 工具检查当前运行时工具注册表 → 复制标准模式的组装并删去 web 工具行 → 在 ${DSH_HOME:-$HOME/.dsh}/.agent-presets/no-web/ 下生成 agent.cordis.yml + preset.yml（一个 preset 一个目录，不是单个 yml 文件）。不要改动 shipped preset 的安装目录——升级会被覆盖，应复制后改副本。

关键约束：

• 创造模式的 cordis_* 工具等同于 shell 级访问权限（cordis_mount 会对 live 运行时执行模型写的 JavaScript）——谨慎使用
• preset 是 agent.cordis.yml 组装文件，不同 preset 的会话在同一进程中隔离运行
• 新 preset 需要新开会话才能在 UI 选择器中看到

第 6 章：高级工具——workflow 与 ralph

本章说明：workflow 和 ralph 是工具而非模式，在标准模式下即可使用。之所以独立成章，是因为其复杂度高于日常场景，仅在用户明确要求时使用。

6.1 workflow：多阶段 / 多角度编排

适用：跨多个文件的审计、一次迁移、多角度研究。一两项委派应使用普通 subagent。

核心机制：模型运行 JavaScript 编排脚本，把工作委派给多个 subagent，并返回脚本的最终 JSON 值。脚本可用 agent()、parallel()、pipeline()、phase() 和 log()。

最小案例：并行审查 3 个文件的正确性。

用户消息：

1
2

用 workflow 并行审查 src/a.ts、src/b.ts、src/c.ts 的正确性问题。
每个文件一个 subagent，最后汇总。

预期 DSH 行为：提交 workflow 工具调用，script 中包含：

1
2
3
4
5
6

const reviews = await parallel([
  () => agent('Review src/a.ts for correctness'),
  () => agent('Review src/b.ts for correctness'),
  () => agent('Review src/c.ts for correctness'),
]);
return { reviews };

关键约束：

• 父级轮次等待所有委派结束；取消或异常返回错误，不报部分成功
• 模型只看到最终结果，永远看不到中间子 agent 消息
• maxResultChars 默认 50000，更长 JSON 被截断

6.2 ralph：每轮全新 agent 迭代

适用：用户明确要求“每轮全新 agent 迭代”。普通长任务用 /goal，有界委派用 subagent / workflow。

核心机制：固定前台循环——每轮一个全新子 agent 针对同一个不可变目标工作，只传递上一轮的 bounded structured report 和共享工作区状态。

最小案例：一个需要多轮迭代才能稳定的算法优化。

用户消息：

1
2
3

用 ralph 迭代优化 src/algo.ts 的性能，
目标：benchmark 从 120ms 降到 80ms 以下。
最多 10 轮。

预期 DSH 行为：调用 ralph({ objective: "...", maxRounds: 10 })，阻塞直到整个运行结束。每轮新 agent 读上一轮报告继续推进。

关键约束：

• 子 agent 的 complete / blocked 报告不经过独立验证——worker 自报完成
• 父对话和之前子会话永远不复制到新一轮
• maxRounds 的配置值既是默认也是单次调用的上限：包级默认 256，但 shipped 的 standard / PTC preset 均配为 64——Web GUI 里实际默认与上限是 64（需更高上限要改 preset 配置）
• 返回 complete / blocked / budget-limited，携带最后一轮报告和轮数

第 7 章：plan/spec 自动检查

重要说明：plan/spec 章节完整性检查不是 DSH 内建功能，但自 v0.1.5 起发行版原生内置 Claude Code 兼容 hooks 桥（@deepseek-ai/dsh-hooks-claude-code），可直接在 PreToolUse 拦截 exit_plan_mode 实现检查，无需第三方插件；社区插件在此之上提供项目层自动发现等增强。CI 门禁为另一独立方案。

7.1 方案总览

7.2 方案 A：原生 hooks 拦截 plan 提交

官方桥 dsh-hooks-claude-code 复用 Claude Code 的 hooks 协议，把事件接到 DSH 的生命周期缝上。关键事件：

落地步骤：

1. 在 profile 的 cordis 组合中挂载官方桥（在 $DSH_HOME/profiles/web/cordis.patch.yml 追加一行），显式指定配置文件（原生桥无自动发现）：

1
2
3
4

- name: '@deepseek-ai/dsh-hooks-claude-code'
  config:
    configPath: ./hooks.json   # 也接受"hooks 键持有配置"的 settings 文件
    projectDir: .

2. 创建 hooks.json：

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

{
  "PreToolUse": [
    {
      "matcher": "exit_plan_mode",
      "hooks": [
        {
          "type": "command",
          "command": "node \"${CLAUDE_PROJECT_DIR}/scripts/check-plan-sections.mjs\"",
          "timeout": 10
        }
      ]
    }
  ]
}

3. 编写检查脚本 scripts/check-plan-sections.mjs：

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

// 从 stdin 读取 JSON payload
let input = '';
process.stdin.on('data', (chunk) => { input += chunk; });
process.stdin.on('end', () => {
  const payload = JSON.parse(input);
  const plan = payload.tool_input?.plan || '';
  const required = ['## 目标', '## 验收标准', '## 实施步骤', '## 风险与回滚'];
  const missing = required.filter((s) => !plan.includes(s));
  if (missing.length > 0) {
    console.error(`Plan 缺少章节：${missing.join('、')}。请补齐后重新提交。`);
    process.exit(2); // Exit 2 = 阻断，stderr 作为反馈交给模型
  }
  process.exit(0);
});

工作原理：钩子脚本从 stdin 接收 JSON payload（含 tool_input），取 plan 内容检查必需章节。缺失时以 Exit 2 返回，stderr 中的提示信息作为反馈交给模型，模型自动修订 plan 后重新调用 exit_plan_mode，钩子重新校验。

路径两个坑：

• 钩子命令的工作目录是会话 cwd，不是 projectDir——projectDir 只喂 ${CLAUDE_PROJECT_DIR} 变量替换和同名环境变量，所以脚本路径要用 ${CLAUDE_PROJECT_DIR} 锚定（如上例），裸写相对路径在会话目录 ≠ 项目根时找不到脚本。
• configPath: ./hooks.json 的相对基准是 dsh 宿主进程的启动目录，多工作区混用时建议写绝对路径。

原生桥的两个边界：PreToolUse 的 deny / ask 生效，但 allow 不预批准、updatedInput 不生效；payload 中 transcript_path 恒为空字符串。钩子超时默认 600 秒，可用条目级 timeout（秒）覆盖。

7.3 方案 A+：社区插件增强

上述 JSON 配置与检查脚本对社区插件 @dennisrongo/dsh-hooks 同样适用（同一 Claude Code 协议）。需要以下增强时改装它：

• 项目层自动发现：<workspace>/.dsh/hooks.json 随仓库提交即生效，无需改 profile 组合；
• 双层叠加：用户层（$DSH_HOME/settings.yaml 的 dsh-hooks 命名空间）与项目层同时生效；
• failClosed：条目加 "failClosed": true 后，钩子崩溃/超时按阻断处理（原生桥无此字段）；
• 支持 8 种事件（另含 SessionStart/SessionEnd/Stop/SubagentStop/Notification）与 skill hints。

安装：dsh plugin add @dennisrongo/dsh-hooks（或 dsh plugin --profile web add ...），装完重启 profile。

7.4 方案 B：CI 门禁

将 spec 完整性检查写成 GitHub Actions job，作为 PR 的必需检查项。核心逻辑：解析 docs/specs/*.md 的 markdown 结构，验证必需章节是否存在且非空。

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

# .github/workflows/spec-check.yml
name: Spec Completeness Check
on: [pull_request]
jobs:
  check-spec:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Check spec sections
        run: |
          shopt -s nullglob  # specs 是条件必需（见 1.3）；无文件时跳过而非误杀
          for f in docs/specs/*.md; do
            for section in "## 背景" "## 验收标准" "## 实施步骤" "## 风险与回滚"; do
              if ! grep -q "$section" "$f"; then
                echo "::error file=$f::$section 缺失"
                exit 1
              fi
            done
          done

7.5 方案 C：专用插件人工审查

@hilariouhiss/dsh-plan-doc 是社区插件，拦截 exit_plan_mode 并将 markdown plan 渲染在右侧抽屉中，供你预览和编辑。面板底部有”确认实施”和”交由模型修改”两个按钮。点击后者时，修改意见作为反馈交回模型，plan mode 保持激活，模型修订后的新稿自动重新打开面板。

能力边界：/plan-doc 只接收面板的 approve / reject 决策，面板仅在拦截 exit_plan_mode 时出现——它不能对任意文件发起审查。因此 spec 审查的可行约定是：在 AGENTS.md 中约定 docs/specs/ 文件的创建或重大修改必须伴随一次 plan mode 流程，把 spec 内容作为 plan 经 exit_plan_mode 提交评审（面板自然渲染该稿），而不是”写完文件再 /plan-doc 审查”。

7.6 规则清单与 AGENTS.md 的对应

自动检查的规则必须与 AGENTS.md 中定义的模板章节一一对应。建议在 AGENTS.md 中新增”自动检查规则”一节（见 1.5 节模板），明确列出：

• exit_plan_mode 的 plan 必须包含：目标、验收标准、实施步骤、风险与回滚。
• docs/specs/*.md 必须包含：背景、验收标准、实施步骤、风险与回滚。
• 实施步骤中每个 Step 必须声明 指令 和 验证 字段。

把这份规则同时写入 AGENTS.md 和钩子脚本，DSH 在修订 plan 时会主动对照规则补全。

第 8 章：项目工程规范（按需）

本章说明：本章不属于 DSH 功能，是对中型团队有价值的项目管理建议，按需阅读。

8.1 CI 守卫

1
2
3
4
5

# ⚠️ 项目自身的 CI 守卫（GitHub Actions 通用写法）
- 改了 src/api/** → 必动 docs/architecture/overview.md 或 specs/
- decisions.md 数量不能减少（防误删）
- AGENTS.md 至少 30 行
- specs/*.md 改了 → 必动 src/ 相关文件

8.2 其他文件维护

runbooks.md / postmortems/ / CHANGELOG.md / README.md 较简单，按需维护即可。

附录 A：速查表

A.1 全部 slash 命令

A.2 主用工具

A.3 高级工具

A.4 sandbox 模式

A.5 4 种 agent 模式一句话选择指南

收尾

一句话：模式选对（90% 标准模式）+ 文档到位（AGENTS.md + architecture + README + 条件 specs）+ 指令纪律（决策树 + 真实约束）= 80% 的稳定性。

剩下 20%——靠团队踩坑反馈、持续更新文档、复杂任务用 plan mode 走流程。

问题现象

启动 dsh web（@deepseek-ai/dsh）后，浏览器访问 http://127.0.0.1:3080 新建会话并提交消息，对话框返回错误：

1

clientTimeZone must be UTC or a valid IANA Area/Location name

服务端响应 { ok: false, error: { code: "invalid-time-zone", details: { value: "Asia/Beijing" } } }。

API 直连复现：

原因分析

请求链路

1

浏览器 → POST /api/session.prompt →  canonicalClientTimeZone() 校验 → Agent

客户端取时区

dsh-client-runtime/lib/client.js:7009：

1
2
3
4
5
6

function resolvedClientTimeZone() {
  const timeZone = new Intl.DateTimeFormat().resolvedOptions().timeZone;
  if (typeof timeZone !== "string" || timeZone.length === 0)
    throw new Error("browser time zone is unavailable");
  return timeZone;
}

浏览器从 OS 读取时区。本机 /etc/timezone = Asia/Beijing，所以浏览器上报 "Asia/Beijing"。

服务端校验

dsh-host-apiproxy/lib/types/api-proxy.js:115-134：

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

const IANA_TIME_ZONE = /^[A-Za-z][A-Za-z0-9_+.-]*(?:\/[A-Za-z0-9_+.-]+)+$/;

function canonicalClientTimeZone(value) {
  if (value.length === 0 || value.trim() !== value
      || (value !== 'UTC' && !IANA_TIME_ZONE.test(value)))
    return undefined;
  try {
    const canonical = new Intl.DateTimeFormat('en-US', { timeZone: value })
      .resolvedOptions().timeZone;
    if (canonical !== 'UTC' && !IANA_TIME_ZONE.test(canonical))
      return undefined;
    return canonical;
  } catch {
    return undefined;
  }
}

校验两关：

1. 字面必须为 "UTC" 或匹配 IANA Area/Location 正则（必须含 /）。
2. Intl.DateTimeFormat({ timeZone }) 必须接受，并且 resolvedOptions().timeZone 回写也通过同样校验。

根因：ICU 78 移除了 Asia/Beijing 别名

1
2
3
4
5

$ node -e 'console.log(Intl.supportedValuesOf("timeZone").filter(z => z.startsWith("Asia/")).length)'
71

$ node -e 'console.log(["Asia/Beijing","Asia/Shanghai","Asia/Chongqing"].map(z => [z, Intl.supportedValuesOf("timeZone").includes(z)]))'
[ [ 'Asia/Beijing', false ], [ 'Asia/Shanghai', true ], [ 'Asia/Chongqing', false ] ]

服务端 ICU 78 不再认识 Asia/Beijing，于是 Intl.DateTimeFormat({ timeZone: 'Asia/Beijing' }) 抛错，canonicalClientTimeZone 返回 undefined，最终被映射成 invalid-time-zone。

注意：/usr/share/zoneinfo/Asia/Beijing 与 /Asia/Shanghai 是同一文件的两个软链（都指向 ../PRC），系统层面行为完全等价，仅名字在 ICU 列表中已被规范化。

解决方法

根本修复：改系统时区

把已被 ICU 移除的 Asia/Beijing 改为仍受支持的 Asia/Shanghai（二者指向同一 tzdata 文件，行为等价）：

1
2
3

sudo ln -sf /usr/share/zoneinfo/Asia/Shanghai /etc/localtime
echo "Asia/Shanghai" | sudo tee /etc/timezone
date

然后重启浏览器（让浏览器重新读取系统时区），刷新 http://127.0.0.1:3080 再提交即可。

临时方案（不动系统时区）

Chrome DevTools → ⋮ → More tools → Sensors → Override timezone 选 Asia/Shanghai。仅对当前 tab 生效，刷新或新开 tab 即失效。

其他常见易踩坑的非法值

服务端正则 ^[A-Za-z][A-Za-z0-9_+.-]*(?:\/[A-Za-z0-9_+.-]+)+$ 要求 Area/Location 形式，以下值都会被拒绝：

经验小结

• Web 应用跨 ICU/浏览器上报时区时，系统时区字符串与 ICU canonical name 不一致 是常见坑。
• 本机 OS 虽保留 Asia/Beijing 的 tzdata 别名（指向 PRC），但运行时的 ICU 已统一为 Asia/Shanghai。
• 排查类似 invalid-time-zone 类问题，先在 Node 端跑一次 Intl.supportedValuesOf("timeZone") 看是否包含浏览器上报值，能快速定位。

基于 deepin 15 / Debian 10 buster 的国产化桌面发行版全方位兼容性评估

操作系统识别

UOS（统信操作系统）由 deepin 团队与统信软件技术有限公司联合开发，定位党政、央企、金融、能源等”信创”市场。本版本对应 deepin 15 SP3/20 同期主线内核，主要面向国产化 PC 平台。

系统技术栈总览

核心运行时栈

1
2
3
4
5
6
7

┌─────────────────────────────────────┐
│  Linux Kernel 4.19.0-amd64-desktop │  ← LTS 分支（Deepin 移植）
├─────────────────────────────────────┤
│  glibc 2.28.35 / GCC 8.3.0 / binutils 2.31.1  ← ABI 基线
├─────────────────────────────────────┤
│  libstdc++ GLIBCXX_3.4.25          │  ← C++ ABI
└─────────────────────────────────────┘

GUI / 应用栈

1
2
3
4
5
6
7

┌────────────────────────────────────────┐
│  DDE (KWin 5.x)  │  GTK 3.24.5        │  ← 默认桌面与原生应用
├────────────────────────────────────────┤
│  Qt 5.11.3 (Core/Gui/Widgets/...)     │  ← deepin / WPS / 部分国产应用
├────────────────────────────────────────┤
│  GLib / GObject                       │  ← C 工具库
└────────────────────────────────────────┘

显示 / 图形栈

1
2
3
4
5
6
7

┌────────────────────────────────────────┐
│  X11 / Xorg 1.20.4  │  Wayland 1.21    │  ← X11 主用
├────────────────────────────────────────┤
│  libGL 1.1.0.3 (Nvidia) │ Mesa 19.2.6 │
├────────────────────────────────────────┤
│  NVIDIA Quadro P1000 4 GB (GLX 4.6)   │  ← 独显
└────────────────────────────────────────┘

核心组件版本详解

核心运行时

GUI 工具包

显示与图形

硬件采样

关键结论

• 编译器能力：GCC 8.3 → C++17 完整支持，C++20 仅实验性；缺 C++23。
• GUI 开发建议：
  • GTK 应用：使用 GTK 3.24；本机缺 GTK 2/4，跨发行版时注意 GTK 2 兼容路径
  • Qt 应用：使用 Qt 5.11（Deepin 改版）；如需 Qt 6 需自行编译或添加 backports 源
• 缺失开发头文件：未安装 *-dev 包，仅运行时库；编译需 apt install libgtk-3-dev qtbase5-dev 等。
• 图形栈：X11 主用 + Wayland 协议栈就绪；NVIDIA 专有驱动 550.120 已就位（GL 4.6），Vulkan 仅加载层待补 ICD。
• 国产化护城河：内核携带 useclinux=1 / ima_appraise=off / 海光 C86 优化等 Deepin 自研补丁链。

与主流发行版横向对比

核心组件对比

GUI 工具包对比

显示与图形对比

综合匹配度评分（越接近 100% 越相似）

关键结论

🎯 最接近的发行版：Debian 10 buster (≈98% 匹配)

• 内核 4.19、GCC 8.3、glibc 2.28、Qt 5.11.3、GTK 3.24 完全一致
• 唯一差异：UOS 用了 Deepin 自维护的 4.19 分支（带国产化补丁链）
• 兼容性结论：二进制级 ABI 兼容，可直接复用 Debian 10 仓库与 .deb 包

次接近：Ubuntu 18.04 bionic (≈92%)

• glibc 2.27 旧于本机 2.28，反向兼容——本机可借 bionic 仓库用，但反过来不行
• 兼容性结论：可运行 bionic 二进制，但本机 ABI 更新，覆盖其上生态

Debian 11 / Ubuntu 20.04 (~80%)

• 仅基础栈接近，glibc 2.31 高于本机 2.28
• 兼容性结论：本机无法直接运行其二进制（GLIBC_2.31 not found），需 chroot / Docker / linglong

Debian 12+ / Ubuntu 22.04+ (<70%)

• GCC 11+、glibc 2.35+、Mesa 22+ 全部高于本机
• 兼容性结论：无法运行其二进制，需容器或升级

重要 ABI 兼容性提示

由于本机 glibc 2.28，以下限制需注意：

兼容情况

二进制兼容等级

软件包兼容矩阵

编译兼容等级

总结

当前系统 ≈ Debian 10 buster + Deepin 国产化适配层 + DDE 桌面栈

• ✅ 软件生态：完全兼容 Debian 10 buster，可直接 apt 复用其仓库；Deepin 同源仓库是首选
• ✅ GUI 编程：GTK 3.24 / Qt 5.11 完整支持，可开发现代桌面应用；Qt 5.15 / Qt 6 需自行编译或走沙箱
• ⚠️ 内核：4.19 LTS 已脱离上游官方支持，靠 Deepin 自维护；国产化补丁链（useclinux / IMA / 海光 C86 优化）是 UOS 的护城河
• ⚠️ ABI 边界：glibc 2.28 是关键上限，无法运行 Debian 11+ / Ubuntu 20.04+ 二进制；引入新版生态需 Docker / linglong
• 💡 升级建议：
  • 短期：通过 linglong / flatpak / Docker 解决新生态兼容问题
  • 长期：评估 UOS 主版本升级路径（V20 → V25 / 1050 / 1060 等），跨主版本升级 ABI 与内核基线会跳一档
  • 选型：如仅需 GNOME / KDE 而非 DDE，建议直接评估 Debian 11 / Ubuntu 22.04 本家发行版

背景与定位

最近接触了一台国产化 PC，搭载的是方德桌面操作系统 V5.0-G240H（NFSChina Desktop OS）。从内核到 GUI 全套看了一遍，发现它本质是 Debian 11 bullseye 的国产化定制版，主要差异在内核主版本和驱动层。

作为开发者，最关心的是：在这台机器上编译的应用能不能跑？Debian/Ubuntu 上的 .deb 能不能直接装？本文做一次系统性的兼容性盘点。

一句话结论：当作 Debian 11 bullseye 或 Ubuntu 20.04 focal 环境使用最稳妥。

一、操作系统识别

方德（FS、NFSChina）是国内操作系统厂商，主攻党政机关、央企、关键行业等信创市场。本版本 G240H 属于桌面端 V5.0 系列，针对国产化 PC 平台优化。

二、系统技术栈总览

2.1 核心运行时栈

1
2
3
4
5
6
7

┌─────────────────────────────────────────┐
│  Linux Kernel 5.4.0-100-generic        │  ← LTS 分支
├─────────────────────────────────────────┤
│  glibc 2.31 / GCC 10.2 / binutils 2.35  │  ← ABI 基线
├─────────────────────────────────────────┤
│  libstdc++ GLIBCXX_3.4.28               │  ← C++ ABI
└─────────────────────────────────────────┘

2.2 GUI / 应用栈

1
2
3
4
5
6
7

┌───────────────────────────────────────────┐
│  GTK 3.24.24 (主)  │  GTK 2.24.33 (老)    │  ← GNOME 应用
├───────────────────────────────────────────┤
│  Qt 5.15.2 (Core/Gui/Widgets/Quick/...)   │  ← KDE/Qt 应用
├───────────────────────────────────────────┤
│  GLib 2.66.8                             │  ← C 工具库
└───────────────────────────────────────────┘

2.3 显示 / 图形栈

1
2
3
4
5

┌───────────────────────────────────────────┐
│  Wayland 1.18  │  X11 1.7.5  │  xcb 1.14  │  ← 双显示协议
├───────────────────────────────────────────┤
│  NVIDIA T400 4GB (GLX 1.4)               │  ← 独显
└───────────────────────────────────────────┘

三、核心组件版本详解

3.1 核心组件

3.2 GUI 工具包

3.3 显示与图形

3.4 关键结论

• 编译器能力：GCC 10.2 → C++20 完整支持，C++23 处于实验性。
• GUI 开发建议：
  • GTK 应用：使用 GTK 3.24（推荐）或 GTK 2（兼容旧程序）
  • Qt 应用：使用 Qt 5.15 LTS；如需 Qt 6 需自行编译或添加 backports 源
• 缺失开发头文件：未安装 *-dev 包，仅有运行时库。如需编译需 apt install libgtk-3-dev qtbase5-dev 等。
• 图形栈：X11 + Wayland 双栈，NVIDIA 专有驱动已就位（GLX 1.4）。

四、与主流发行版的详细对比

4.1 核心组件对比

4.2 GUI 工具包对比

4.3 显示与图形对比

4.4 综合匹配度评分

越接近 100% 表示技术栈越相似，二进制/源码级兼容性越好。

4.5 关键结论

🎯 最接近的发行版：Debian 11 bullseye（≈92% 匹配）

• 编译器（GCC 10.2.1）、glibc 2.31、GTK 3.24.24、Qt 5.15.2 完全一致
• 唯一差异：内核主版本 5.4 vs 5.10（方德用了更早的 5.4 LTS 分支）
• 兼容性结论：二进制级 ABI 兼容，可直接使用 Debian 11 仓库

次接近：Ubuntu 20.04 focal（≈88%）

• glibc、GTK 2、内核主线一致
• Qt5（5.15 vs 5.12）和 X11（1.7 vs 1.6）略新
• 兼容性结论：运行 Ubuntu 20.04 二进制安全，可直接借用其 PPA

Ubuntu 22.04 jammy（≈75%）

• 仅 X11 一致，其他组件比当前系统都新
• 兼容性结论：当前系统无法直接运行 jammy 二进制（glibc 2.35 要求高于本机 2.31）

4.6 重要 ABI 兼容性提示

由于当前系统 glibc 2.31，以下限制需注意：

最终建议：当作 Debian 11 bullseye 或 Ubuntu 20.04 focal 环境使用最稳妥，可直接使用对应的 .deb 软件包与 apt 源。Ubuntu 22.04 及以后的二进制需要 Docker/chroot 运行。

五、兼容情况

5.1 二进制兼容等级

5.2 软件包兼容矩阵

5.3 编译兼容等级

六、总结

当前系统 ≈ Debian 11 bullseye + 国产化适配层

• ✅ 软件生态：完全兼容 Debian 11，可用 apt 源直接扩展
• ✅ GUI 编程：GTK 3.24 / Qt 5.15 完整支持，可开发现代桌面应用
• ⚠️ 内核：5.4 LTS 偏旧，但稳定可靠，足够支撑桌面与服务器场景
• ⚠️ ABI 边界：glibc 2.31 是关键上限，不能运行更新的发行版二进制
• 💡 升级建议：若需运行新版生态，可通过 Docker 解决；若需大规模生产部署，建议直接以 Debian 11 / Ubuntu 20.04 为目标

选型核心只有一句话：glibc ≤ 2.31 的世界就是这台机器的舒适区。

背景与场景

三维重建是测绘、GIS、影视、游戏、VR 等多个行业的底层技术。近两年”3D 高斯飞溅（3D Gaussian Splatting，下文简称 3D-GS）”凭借惊艳的视觉效果迅速走红，让很多人开始重新评估自己的技术路线：传统”倾斜摄影测量”是不是要被取代了？

答案没那么简单。两者定位完全不同 —— 一个是测量级工具，输出可量测的几何模型；一个是渲染级工具，输出可实时显示的辐射场。把它们当作”新旧替代关系”是典型误读。本文从原理、输出、精度、应用四个维度做一次系统梳理，帮你按需选型。

一、技术原理

1.1 倾斜摄影测量（Oblique Photogrammetry）

倾斜摄影测量是摄影测量学的成熟分支：通过无人机搭载多镜头相机（通常五镜头），从多个角度对同一地物拍摄大量带有重叠度的照片，再借助特征点匹配（SIFT / SFM）和多视密集匹配（MVS），反算出每个像素对应的空间坐标，最终生成带真实纹理的三角网格（Mesh）和纹理贴图。

1.2 3D 高斯飞溅（3D Gaussian Splatting）

3D-GS 是 2023 年由 INRIA 提出的新型神经渲染方法。它把场景表示为海量可微分的 3D 高斯椭球（每个椭球带位置、协方差、颜色、透明度），通过 SfM 初始化后用 GPU 迭代优化，最终在任意视角下通过”飞溅投影”实时合成图像。

二、核心区别

关键差异：倾斜摄影测量输出的 Mesh 在 GIS 软件里可以直接量距离、面积、体积，3D-GS 输出在视觉上很美但”几何是隐式的”，无法直接拿到准确尺寸。

三、典型应用场景

3.1 倾斜摄影测量

3.2 3D 高斯飞溅

四、技术选型建议

五、代表产品速览

六、总结

两种技术不是替代关系，而是互补关系：

• 倾斜摄影测量 → 测绘、工程、政府项目、可量测场景的标准答案；
• 3D 高斯飞溅 → 视觉表现、实时渲染、消费级体验的更优解。

如果项目对”几何精度”敏感，就老老实实用倾斜摄影测量；如果项目对”画面真实感和实时性”敏感，3D-GS 是 2024 年以来的最优解。预算充足、要求高的话，可以把两者结合 —— 用倾斜摄影测量保证几何骨架，用 3D-GS 渲染贴层做视觉增强。

选型核心只有一句话：你的项目到底是”要测”还是”要看”？

前言：为什么必须锁定 2.1.153

Claude Code 在近期版本迭代中，对第三方自定义模型做了强制封杀，版本分界线非常明确：

• ≤ 2.1.153：完全原生支持 ANTHROPIC_BASE_URL 自定义接口，兼容所有国产 Anthropic 协议模型，无请求篡改、无强制登录、无报错。
• 2.1.154 ~ 2.1.155：强制插入非法 system 字段，第三方模型全部 400 报错。
• ≥ 2.1.156：底层彻底移除自定义接口能力，完全无法使用第三方模型。

结论：2.1.153 是目前国内开发者使用第三方模型的唯一终点版本。原本使用的 2.1.146 可直接平滑升级，稳定性大幅提升且完全保留第三方兼容性。

一、定点安装 / 升级至 2.1.153

使用官方原生安装脚本定点安装指定版本，无需卸载旧版本，直接覆盖升级，保留用户目录配置。

macOS / Linux / WSL

1

curl -fsSL https://claude.ai/install.sh | bash -s 2.1.153

Windows PowerShell（管理员）

1

& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) 2.1.153

版本校验

安装完成后重启终端，执行如下命令确认版本锁定成功：

1

claude --version

正常输出：Claude Code 2.1.153

二、永久锁定版本，彻底禁用自动更新

这是最重要步骤。不锁版本会被后台静默升级至失效版本，导致第三方模型彻底无法使用。采用「配置文件+系统环境变量」双重兜底方案。

2.1 全局配置文件锁定

编辑配置文件：

• macOS / Linux：~/.claude/settings.json
• Windows：%USERPROFILE%\.claude\settings.json

写入以下完整配置：

1
2
3
4
5
6
7
8
9

{
  "autoUpdates": false,
  "autoUpdatesChannel": "stable",
  "minimumVersion": "2.1.153",
  "env": {
    "DISABLE_AUTOUPDATER": "1",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  }
}

配置说明：

• 关闭客户端自动更新：禁止客户端主动检测、下载、升级新版本
• 禁用官方更新进程：通过官方环境变量彻底杀死更新服务
• 关闭非必要遥测：减少国内网络无效请求，降低卡顿与延迟

2.2 系统环境变量兜底加固

macOS / Linux（zsh/bash）

1
2

echo 'export DISABLE_AUTOUPDATER=1' >> ~/.zshrc
source ~/.zshrc

Windows PowerShell

1

[Environment]::SetEnvironmentVariable("DISABLE_AUTOUPDATER", "1", "User")

三、国内环境专属优化方案

• 精简 MCP 服务：未使用 MCP 工具链时，清空所有 MCP 服务，减少后台常驻占用

  1 2	claude mcp list claude mcp remove 服务名

• 定期压缩上下文：长对话卡顿、上下文冗余，在 Claude 终端输入 /compact 一键精简会话
• 管控后台任务：避免大量并行 /bg 后台任务，防止守护进程残留卡死
• 清理缓存：定期删除 ~/.claude/cache 缓存目录，不影响配置与密钥

四、macOS / Linux 一键终极部署脚本

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

curl -fsSL https://claude.ai/install.sh | bash -s 2.1.153
cat > ~/.claude/settings.json << 'EOF'
{
  "autoUpdates": false,
  "autoUpdatesChannel": "stable",
  "minimumVersion": "2.1.153",
  "env": {
    "DISABLE_AUTOUPDATER": "1",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  }
}
EOF
echo 'export DISABLE_AUTOUPDATER=1' >> ~/.zshrc
source ~/.zshrc
claude --version

结语

目前 Claude Code 官方持续收紧第三方模型权限，2.1.153 是国内免费自定义模型的最后窗口期版本。

大语言模型的规模增长面临算力与存储的双重约束。如何在保持模型能力的前提下降低推理成本，已成为工业落地的核心命题。MoE（混合专家模型）、稀疏参数与知识蒸馏三项技术从不同维度破解这一困境：MoE通过动态激活部分参数实现稀疏化，稀疏参数释放了规模化的潜力，知识蒸馏则将大模型能力迁移至小模型。三者协同，代表了大模型从”大而强”走向”大而轻”的主流技术路径。

MoE：稀疏激活的神经网络架构

MoE的核心思想是”分而治之”。传统神经网络对所有输入执行相同的计算路径，而MoE将模型分解为多个并行的专家网络（Expert Networks），由一个门控网络（Gating Network）根据输入内容动态选择激活哪些专家。

具体而言，门控网络为每个输入token输出一组权重分布，决定各专家的参与程度。推理时，只有权重较高的少数专家被实际调用，其余专家的计算被跳过。以DeepSeek-R1-671B为例，其总参数规模为671B，但推理时每次仅激活约1/10的专家，单步计算量等价于一个67B的稠密模型。这意味着模型在拥有超大规模参数的同时，将实际计算成本控制在远低于总参数的量级。

MoE的优势在于：相同算力预算下可以容纳更多参数，从而突破稠密模型的规模瓶颈；不同专家可专注于不同类型的任务或知识领域，实现隐式的专业化分工。

稀疏参数：规模与效率的重新平衡

稀疏参数并非MoE独有，但MoE是其最典型的工程实现。稀疏的含义是：总参数量巨大，但任意时刻只有部分参数被实际使用。

这一特性带来三方面价值。首先是规模突破：在相同的算力和显存约束下，稀疏模型可以拥有10-100倍于稠密模型的参数量，因为大部分参数无需同时参与计算。其次是推理成本降低：激活参数少意味着每次前向传播的FLOPs大幅减少，部署成本随之下降。第三是专业化分工：不同专家可学习不同领域的知识，形成隐式的任务路由，避免单一模型试图同时掌握所有能力导致的表达冲突。

稀疏参数的本质是用”参数冗余”换取”计算高效”——存储的是大规模知识，执行时只调用与当前输入相关的部分。

知识蒸馏：从大模型到小模型的能力迁移

知识蒸馏（Knowledge Distillation）是将大模型（教师模型）能力迁移至小模型（学生模型）的技术。其核心机制是让小模型不仅学习硬标签（真实标签），还学习软标签（教师模型输出的概率分布）。

软标签包含的信息远多于硬标签。硬标签只告诉模型”正确答案是什么”，而软标签还携带了”错误答案之间的相对关系”——模型认为”猫”和”狗”的相似度高于”猫”和”汽车”，这种隐含的相似结构正是知识蒸馏希望传递的”暗知识”。

以DeepSeek-R1-Distill系列为例，教师模型为DeepSeek-R1-671B（MoE架构），学生模型则包括Qwen系（1.5B/7B/14B/32B）和Llama系（8B/70B）等多个规模的稠密模型。蒸馏后的小模型在保持极小参数量的同时，复现了教师模型在推理任务上的核心能力。

三者协同：技术飞轮的运转逻辑

三项技术的协同构建了一个高效的技术飞轮。

MoE提供了”超强教师”的可能——凭借稀疏激活，MoE模型可以在总参数极大的同时保持推理效率，这意味着教师模型可以拥有前所未有的知识容量和多样性。知识蒸馏则充当”能力搬运工”，将教师从海量参数中习得的知识以软标签的形式传递给轻量的学生模型。稀疏参数是连接两者的桥梁——它既是MoE的实现基础，也是蒸馏得以可行的前提，因为只有稀疏架构才能在保持大规模知识的同时具备足够的推理效率来完成蒸馏过程。

最终实现的效果是”高性能+低成本”的落地：教师模型负责知识生产和能力探索，学生模型负责实际部署和服务。这种分工在保持能力上限的同时，大幅降低了端侧部署的门槛。

总结

MoE通过稀疏激活打破了”参数量=计算量”的等式约束，为大规模模型的训练提供了新的可行路径。稀疏参数将这一优势工程化，实现规模与效率的重新平衡。知识蒸馏则在不损失核心能力的前提下，将大模型的优势迁移到可部署的轻量模型。三项技术共同推动了大模型从”大而强”向”大而轻”的关键演进，为AI能力的广泛落地扫清了算力壁垒。

通义千问 Qwen3.6-35B-A3B + 视觉能力，8G 显存、32G 内存，Windows 部署

前言

大模型常被认为是高端显卡的专属，动辄 24G、48G 显存门槛劝退普通玩家。但随着 llama.cpp 高性能推理 + GGUF 量化 + MoE 混合专家架构 的成熟，8G 消费级显卡也能跑 35B 级大模型，甚至带视觉能力。

本文全程基于 RTX 4060 8G + 32G 内存 + Windows，手把手部署 Qwen3.6-35B-A3B MoE（含视觉），无编译、无高门槛、可直接照抄操作。

一、硬件与模型选型

1.1 硬件配置（真实消费级）

• 显卡：NVIDIA RTX 4060 8GB（GDDR6）

• CPU：Intel i9-11900KB @ 3.30GHz

• 内存：32GB DDR4（双通道，关键！）

• 系统：Windows 11 64 位

1.2 选用模型详解

本次部署 通义千问 35B MoE 量化版 + 视觉投影：

• 主模型：Qwen3.6-35B-A3B-UD-Q4_K_M.gguf（4-bit 量化，平衡速度 / 效果）

• 视觉投影：mmproj-BF16.gguf（支持图文对话、图片理解）

1.2.1 模型命名解析（A3B 与 UD）

1.2.2 选择理由

• MoE 架构优势：总参数 35B，推理只激活少量专家，显存占用远低于同规模稠密模型

• UD-Q4_K_M 量化：动态量化 + 混合精度，显存大幅下降，适配 8G+32G 配置

• 原生视觉能力：内置视觉编码器，开箱即用图文对话

• 开源生态成熟：Unsloth 提供 GGUF 版本，兼容性好、社区支持完善

二、环境安装（Windows，一键到位）

2.1 安装 CUDA 12.4（必须，13.2 有兼容问题）

管理员 PowerShell 执行：

1

winget install NVIDIA.CUDA.12.4

安装完成后重启电脑。

2.2 下载预编译 llama.cpp（免编译）

1. 发布页：https://github.com/ggerganov/llama.cpp/releases

2. 下载：llama-b9305-bin-win-cuda-12.4-x64.zip

3. 解压到目录，例如：D:llama.cpp

2.3 安装 uv + huggingface-hub（uv tool）

2.3.1 安装 uv

1

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

2.3.2 安装 huggingface-hub

1

uv tool install huggingface-hub

验证：

1

huggingface-cli --version

2.4 永久配置 HF 国内镜像（hf-mirror）

镜像地址：https://hf-mirror.com

管理员 PowerShell 执行：

1

setx HF_ENDPOINT "https://hf-mirror.com" /M

或手动添加系统环境变量，重启终端生效。

2.5 下载模型（hf-mirror 加速）

进入 llama.cpp 目录，创建文件夹：

1

mkdir -p models/Qwen3.6-35B-A3B-UD-Q4_K_M

下载命令：

1

hf download unsloth/Qwen3.6-35B-A3B-GGUF Qwen3.6-35B-A3B-UD-Q4_K_M.gguf mmproj-BF16.gguf --local-dir ./models/Qwen3.6-35B-A3B-UD-Q4_K_M

三、启动脚本与参数详解（8G 最优配置）

在 llama.cpp 目录新建 start.bat：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

@echo off
chcp 65001 >nul
title Qwen3.6-35B-A3B MoE + 视觉模型
echo ======================================================
echo        通义千问35B MoE + 视觉模型 稳定加速版
echo           硬件：RTX4060 8G + 32G 内存
echo ======================================================
echo.

cd /d "%~dp0"

llama-server.exe ^
-m "./models/Qwen3.6-35B-A3B-UD-Q4_K_M/Qwen3.6-35B-A3B-UD-Q4_K_M.gguf" ^
--mmproj "./models/Qwen3.6-35B-A3B-UD-Q4_K_M/mmproj-BF16.gguf" ^
-ngl 99 ^
--n-cpu-moe 32 ^
-np 1 ^
--flash-attn on ^
--jinja ^
-c 32768 ^
-t 16 ^
-b 1024 ^
-ub 256 ^
--split-mode layer ^
--cache-type-k q4_0 ^
--cache-type-v q4_0 ^
--no-mmap ^
--host 127.0.0.1 ^
--port 8080 ^
--metrics

echo.
echo 启动成功！浏览器访问：http://127.0.0.1:8080
pause

关键参数解析

四、运行效果（8G 显卡真实表现）

4.1 启动与访问

1. 双击 start.bat

2. 首次加载约 1–2 分钟

3. 浏览器打开：http://127.0.0.1:8080

4.2 资源占用

• 显存：7.2–7.8GB（稳定不溢出）

• 内存：16–20GB（专家层分流）

• CPU：90%（负载可控）

4.3 推理速度

• 文本对话：30 token/s（日常流畅）

• 图文对话：响应 2–3 秒，识别准确

4.4 能力表现

• 文本：问答 / 推理 / 创作接近原生 35B

• 视觉：图片描述、OCR、简单图像问答可用

4.5 稳定性

连续运行 4 小时无崩溃，长文本对话不掉链。

五、效果截图

图 1：启动脚本运行成功界面

图 2：Web 交互主界面

图 3：GPU 显存占用监控

图 4：图文对话示例

六、总结

RTX 4060 8G 真的能跑 35B MoE + 视觉。核心要点：

• CUDA 12.4 + llama.cpp 预编译，避开兼容问题

• UD-Q4_K_M 量化 + KV 缓存量化，适配 8G 显存

• MoE 专家分流到内存，32G 内存成为关键

• hf-mirror 加速，国内高速下载模型

这套方案成本极低、操作极简、效果可用，普通消费卡也能体验 35B 级大模型能力。

目标

解决 Hexo 博客中 LaTeX 矩阵公式（如 bmatrix）被渲染成单行的问题，使多行矩阵正确显示为多行结构。

前置条件

• Node.js 环境
• 已有的 Hexo 博客项目
• 使用 NexT 主题

环境安装

安装依赖

1

npm install hexo-filter-mathjax@0.3.1 mathjax@3.2.2 --save

站点配置

在 _config.yml 中添加：

1
2
3
4

mathjax:
  enable: true
  per_page: false
  tags: none

注意：tags 不要写成 mathjax，否则 hexo generate 时会报 ReferenceError: mathjax is not defined。

关闭 NexT 主题前端 MathJax

NexT 主题会在前端加载自己的 MathJax CDN，与服务端渲染冲突。在主题 _config.yml 中关闭：

1
2
3
4
5

math:
  mathjax:
    enable: false
  katex:
    enable: false

核心：矩阵行尾反斜杠数量

这是最容易踩的坑。hexo-renderer-marked 在处理 Markdown 时，会将行末的反斜杠数量减半：

结论：非最后一行矩阵数据行尾必须写 4 个反斜杠 \\\\

正确写法示例

1
2
3
4
5
6
7

$$
X=
\begin{bmatrix}
1 & 2 & 3 & 4 \\\\    ← 非最后行：4个反斜杠
2 & 1 & 4 & 3         ← 最后行：无反斜杠
\end{bmatrix}
$$

1
2
3
4
5
6
7
8
9

$$
W_Q=
\begin{bmatrix}
0.1 & 0 & 0 & 0 \\\\
0 & 0.2 & 0 & 0 \\\\
0 & 0 & 0.3 & 0 \\\\
0 & 0 & 0 & 0.4
\end{bmatrix}
$$

下划线处理：operatorname

\text{FFN_State} 中的下划线在 MathJax 的 text 模式下不合法，会导致错误并 fallback 为纯文本。用 operatorname 替代：

验证方法

本地预览

1

npx hexo server -p 4000

检查 mtr 数量

mtr 是 MathJax 的矩阵行元素，有几个 mtr 就有几行：

1

grep -o 'data-mml-node="mtr"' public/文章路径/index.html | wc -l

多行矩阵应该 mtr ≥ 2。单行公式 mtr = 0 是正常的。

浏览器控制台验证

1
2

document.querySelectorAll('mjx-container').length   // 总容器数
document.querySelectorAll('[data-mjx-error]').length // 错误数，应为 0

常见问题

矩阵还是单行显示怎么办？

检查矩阵数据行尾的反斜杠数量：

1
2
3
4
5

with open('source/_posts/文章.md') as f:
    for i, line in enumerate(f, 1):
        if '&' in line and line.rstrip().endswith('\\'):
            bs = line.rstrip().count('\\')
            print(f"line {i}: {bs} backslashes {'✓' if bs == 4 else '✗ NEEDS FIX'}")

输出应有 4 backslashes ✓，否则需要修复。

配置报错 ReferenceError: mathjax is not defined

检查 _config.yml 的 mathjax.tags 是否写成了 mathjax，应改为 none。

浏览器控制台有 '_' allowed only in math mode 错误

使用了 \text{FFN_State}，下划线不合法。改用 \operatorname{FFN_State}。

总结

修复 Hexo 矩阵渲染只需记住两件事：

1. 4个反斜杠：非最后行行尾写 \\\\
2. operatorname：含下划线的标识符用 \operatorname 代替 \text

其他配置（hexo-filter-mathjax、关闭 NexT MathJax）只需设置一次，后续写矩阵公式时遵循上述格式即可。