版本标注：本文已对照 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。

⚠️ sed -i 在 GNU sed（Linux）与 BSD sed（macOS）上语法不同：BSD/macOS 必须写成 sed -i '' 's/.../.../' file，否则 -i 后的 s/.../.../ 会被当作备份文件后缀。跨平台项目建议改用 Node 或 perl -pi -e 改写。

关键约束：

• 持久 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 走流程。

三维重建是测绘、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 渲染贴层做视觉增强。

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

通义千问 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

hf --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 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. 图 1：模型启动后资源占用 —— 对应 4.1 节图片 /assets/llm_start.png
2. 图 2：模型生成过程资源占用 —— 对应 4.2 节图片 /assets/llm_decode.png
3. 图 3：模型生成界面 —— 对应 4.3 节图片 /assets/llm_speed.png
4. 图 4：模型生成速度 —— 对应 4.3 节图片 /assets/llm_speed2.png

六、总结

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

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

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

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

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

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

一、三层架构概览

二、全局配置层

所有项目共享的配置，定义 Claude Code 的全局行为：

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

{
  "env": {
    "ANTHROPIC_MODEL": "MiniMax-M2.7"
  },
  "permissions": {
    "allow": [
      "Bash(uv sync *)",
      "Bash(git log --oneline -20)"
    ]
  },
  "enabledPlugins": {
    "superpowers@claude-plugins-official": true,
    "remember@claude-plugins-official": true
  }
}

核心配置项包括：

• env — API key、全局默认模型
• permissions — 所有项目都允许的 Shell 命令
• enabledPlugins — 全局启用的插件

三、项目配置层

单个项目专属的配置，通常与项目代码一起版本控制：

1
2
3

tender-info/
└── .claude/
    └── settings.local.json

1
2
3
4
5
6
7
8
9

{
  "permissions": {
    "allow": [
      "Bash(uv sync *)",
      "Bash(uv venv *)",
      "Bash(git -C /Volumes/hai/code/tender-info log --oneline -5)"
    ]
  }
}

项目配置文件的作用是记录该项目额外允许的 Shell 命令权限，避免每次操作都弹出权限提示。

四、项目记忆层

严格按项目路径隔离的记忆系统，存放项目相关的持久上下文：

1
2
3

~/.claude/projects/-Volumes-hai-code-tender-info/memory/
├── MEMORY.md
└── python-dependency-management.md

4.1 记忆文件类型

4.2 记忆格式

每条记忆为独立 Markdown 文件，含 frontmatter：

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

---
name: python-dependency-management
description: 用户级Python依赖管理原则
type: user
originSessionId: 46dcfe60-6dcb-4824-850e-41e8ccc11b8f
---

## 具体内容

用户使用 **uv** 管理 Python 项目：
1. uv sync：主要命令
2. uv run：直接运行脚本

MEMORY.md 作为索引文件，每次会话自动加载；具体记忆文件在上下文相关时自动应用。

五、remember 插件 — 会话交接机制

remember 插件是记忆系统的补充机制，解决「跨时间连续性」问题。

5.1 与 memory/ 的区别

5.2 文件格式

1
2
3
4
5
6
7
8
9
10

# Handoff

## State
{已完成什么、未完成什么。文件、MR 号、决策。最多 2-4 行。}

## Next
{接下来要做什么。按优先级排列。1-3 项。}

## Context
{非显而易见的坑、阻碍、本次偏好。如无内容可省略。}

5.3 使用规则

六、三层关系全景图

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

~/.claude/
├── settings.json              ← 【全局】所有项目共享
│   ├── env (API key, 模型)
│   ├── permissions (允许的命令)
│   └── enabledPlugins
│
├── projects/                  ← 【记忆】按项目路径隔离
│   └── -Volumes-hai-code-tender-info/
│       └── memory/
│           ├── MEMORY.md       ← 索引
│           └── *.md            ← 具体记忆
│
tender-info/                   ← 【项目】
├── .claude/
│   └── settings.local.json    ← 项目级权限
├── .remember/
│   └── remember.md            ← 会话交接（remember 插件）
└── ...项目文件

七、设计思想

三层设计体现了关注点分离原则：全局配置、项目配置、项目记忆三者职责清晰不混淆。memory/ 和 remember 解决不同维度的问题——前者是「项目画像」，后者是「时间线快照」。

理解这四层的区别，就能理解为什么没有一个「跨项目全局记忆」——因为全局配置（settings.json）解决的是工具能力，而非项目上下文。

一、大模型推理的正确流程（总览）

许多人对流程的理解存在偏差。下图是标准自回归模型（如GPT）的完整步骤：

1

输入提示词 → 分词 → 嵌入 → 预填充（构建KV缓存） → 自回归生成（逐Token采样） → 输出

• 分词与嵌入：将原始文本拆分为Token，并映射为稠密向量。
• 预填充：一次性计算所有输入Token的Key、Value向量并缓存。此阶段计算密集，但只做一次。
• 自回归生成：逐个产生新Token，每步仅计算新Token的K/V并复用缓存。根据采样策略，输出可能确定或随机。

以下各章将按此顺序逐一详解。

二、分词与嵌入：从文字到向量

2.1 什么是Token？

• 模型不直接认识文字，需要先将输入文本拆分为最小处理单元——Token。
• 对于中文，一个Token可以是字、词或子词。例如”机器学习”可能分成 ["机器", "学", "习"]。

❗ 常见误解：Token化就是传统的中文分词（如jieba）。
✅ 正确理解：Token化会切得更细，常常把完整词拆成常见的片段（如”学习”拆为”学”和”习”），目的是控制词汇表大小并覆盖所有字符。

2.2 模型会把中文翻译成英文再处理吗？

❗ 常见误解：听说某些模型不支持中文，会把中文先翻译成英文再分token。
✅ 正确理解：绝对不会。模型只处理你输入的原始文本的UTF-8字节或直接包含中文词表。如果词表没有中文，每个汉字会变成3个字节Token（如”中” → <0xE4> <0xB8> <0xAD>），这是字节级编码，不是翻译。

2.3 嵌入向量：赋予Token数学含义

• 每个Token通过查一个可学习的嵌入表，得到一个固定维度的稠密向量（如768维），称为嵌入向量。
• 相同Token永远映射到相同嵌入向量（不考虑位置编码时），因此是静态的。
• 嵌入向量是模型的原始输入特征，携带该Token的基础语义信息。

三、预填充阶段：构建KV缓存

当整个输入序列的嵌入向量准备好后，模型进入预填充（Prefill）阶段。这一步会一次性计算所有Token的Key、Value向量并缓存，供后续生成复用。

3.1 从嵌入向量到Key/Value

• 每个Token的嵌入向量 X 分别乘以三个可训练的权重矩阵：

  1	Q = X · W_Q, K = X · W_K, V = X · W_V

• 其中 W_K, W_V 将嵌入”加工”为专门用于注意力机制的Key向量和Value向量。

❗ 常见误解：Key/Value向量就是嵌入向量，只是换个名字。
✅ 正确理解：嵌入向量是原料，Key/Value是从原料加工出来的专用工具。嵌入用于表示Token本身，Key用于匹配注意力权重，Value用于提供加权内容。三者完全不同。

• Key用于匹配相关度（与其他Token的Query计算注意力权重）。
• Value用于提供内容（根据权重加权求和，得到输出）。

通俗类比：

3.2 KV缓存：为什么能省计算？

• 在自注意力中，每个Token都需要所有Token的Key和Value。如果每次生成新Token都重新计算整个序列的K/V，成本极高。
• 预填充阶段一次性算好所有Token的K/V，并存入KV缓存。之后每生成一个新Token，只需计算该Token自己的K/V，追加到缓存中即可。
• 相同输入的前缀，其缓存可直接复用——这就是缓存命中的基础。

3.3 确定性说明

❗ 常见误解：因为模型有随机性，所以预填充的结果也可能每次不同。
✅ 正确理解：在推理模式下（关闭Dropout等随机层），相同的输入序列 → 相同的嵌入 → 相同的K/V → 预填充结果完全确定。模型的随机性只出现在后续的生成采样阶段。

四、自回归生成阶段：逐Token采样与输出

预填充完成后，模型进入自回归生成阶段，逐个产生新的Token。

4.1 每一步做什么？

1. 利用已有的KV缓存（包含输入序列及之前已生成的所有Token），计算下一个Token的概率分布。
2. 根据采样策略（如温度采样、Top-K、Top-P）随机或确定地选出一个Token。
3. 将该Token追加到序列末尾，计算其K/V并加入缓存。
4. 重复直到遇到结束符或达到最大长度。

4.2 随机性的来源

• 如果使用贪心搜索（每次选概率最高的Token），输出完全固定。
• 如果使用随机采样（多数API默认），则相同输入可能产生不同输出——这正是常见”模型不听话”的真正原因。

❗ 常见误解：相同输入得到不同输出，是因为模型内部有”随机种子”在预填充阶段就起作用。
✅ 正确理解：随机性只发生在生成阶段的采样。预填充阶段没有任何随机操作。你可以通过设置 temperature=0 或使用贪婪解码来获得完全确定性的输出。

4.3 输出

• 将生成的Token序列通过解码器转换回文本，返回给用户。

4.4 思考型模型：思考过程在哪里？

❓ 常见问题：像 DeepSeek-R1、OpenAI o1 等模型，它们展示的”思考过程”属于流程中的哪个阶段？
✅ 简明答案：思考过程完全属于自回归生成阶段，不是独立阶段。

• 模型在生成最终答案之前，先通过逐Token采样生成一连串表示”思考”的文本（例如”首先，我们需要…”、”因为…所以…”）。
• 这些思考Token和普通输出一样，是利用KV缓存逐步生成的，每一步只计算新Token的K/V。
• 思考过程也具有随机性（如果使用采样）或确定性（如果 temperature=0）。

换句话说：思考过程 = 自回归生成早期产生的一批特殊Token，它既不是预填充，也不是嵌入，而是生成的一部分。

五、缓存命中：省钱的秘密

5.1 什么是KV缓存命中？

• 当你发送新请求时，API服务会检查你的提示词前缀是否与之前某个请求的前缀Token序列完全一致。若是，则直接复用已缓存的K/V，无需重新计算预填充。
• 计费上：缓存命中的输入Token价格通常仅为未命中的10%~20%。

5.2 命中的硬性条件

• 前缀必须从第一个Token开始连续完全相同。哪怕多一个空格、一个换行，或改变顺序，都会导致缓存失效。

❗ 常见误解：只要提示词大致相同，比如改了一个字或加了一个空格，应该还能命中大部分缓存吧？
✅ 正确理解：绝对不能。缓存匹配是严格的字节/Token级别相等。一个空格、一个标点、甚至繁体与简体的差异，都会导致从差异位置开始后续全部无法命中。

示例：

• 请求A：System: 你是个助手 User: 北京天气
• 请求B：System: 你是个助手 User: 上海天气
• 命中 System: 你是个助手 User: 这一连续前缀（前提是长度足够触发折扣）。

5.3 缓存为什么会失效？

• 时间过期（TTL）：每个缓存块有存活时间，通常5~60分钟。每次命中间隔不超过TTL则持续有效，否则被清除。
• 空间淘汰（LRU）：缓存容量有限，长期未命中的旧缓存会被新请求挤掉。
• 内容变更：任何前缀修改（哪怕是一个字、一个标点）都会使原缓存不可用。

5.4 最佳实践：静态在前，动态在后

• 错误的模式：[动态][静态][动态] → 第一个Token不同，后续静态完全无法命中。
• 正确的模式：将所有静态内容连续放在最开头，所有动态内容放在末尾。

❗ 常见误解：可以静态和动态交替放置，只要后面有连续静态就能命中那一段。
✅ 正确理解：不能。因为缓存匹配必须从第一个Token连续一致。一旦第一个位置是动态，整个前缀就断裂了，后面的任何静态都无法被命中。只有把所有静态放在最前面形成连续前缀才能缓存。

示例：

• ❌ 错误：[用户问题] [系统提示词] [随机ID]
• ✅ 正确：[系统提示词] [历史对话] [当前用户问题]

黄金法则：不变的靠前放，多变的放末尾。

六、确定性与随机性总结

若需要完全可复现的结果，可以设置随机种子或使用贪心解码。

结语

理解大模型内部的推理流程，不仅能帮你写出更高效的代码，还能在日常API调用中大幅降低成本。记住两条核心要点：

1. 静态内容永远放在最前面，利用缓存命中节省80%+输入费用。
2. 生成随机性源自采样，并非模型”出错”。

在 Node.js 生态中，包管理工具一直是开发者绕不开的话题。从最初唯一的 npm，到后来崛起的 Yarn，再到今天的主角——pnpm，这场关于“如何更好地管理 JavaScript 依赖”的探索从未停止。

一、pnpm：高性能的 Node.js 包管理工具

pnpm（Performant npm）是一个快速、节省磁盘空间的 JavaScript 包管理器，于 2016 年首次发布。它之所以能脱颖而出，是因为解决了传统包管理工具的三大痛点：

1. 磁盘浪费：npm / Yarn 在每个项目中重复存储相同版本的依赖，占用大量空间。
2. 安装缓慢：反复下载、解压、复制依赖，导致冷启动安装耗时较长。
3. 幽灵依赖：扁平化的 node_modules 允许项目访问未声明的包，埋下兼容性与安全隐患。

pnpm 通过 内容可寻址存储 + 硬链接/符号链接 机制颠覆了依赖管理方式：所有依赖在全局存储中只存一份，项目通过硬链接引用；node_modules 结构严格隔离，彻底杜绝幽灵依赖。这使得 pnpm 在速度、磁盘占用和安全性上都远超传统工具。

二、快速上手指南

2.1 安装

推荐使用独立脚本安装（无需 Node.js 环境）：

• Linux / macOS：

  1	curl -fsSL https://get.pnpm.io/install.sh | sh -

• Windows (PowerShell)：

  1	iwr https://get.pnpm.io/install.ps1 -useb | iex

其他方式：npm install -g pnpm、brew install pnpm、scoop install pnpm 等。

验证安装：pnpm --version

2.2 配置镜像加速（国内用户）

1
2

pnpm config set registry https://registry.npmmirror.com
pnpm config get registry

2.3 基础命令速查

2.4 深入理解：install 与 add 的区别（npm vs pnpm）

习惯建议：在团队中统一约定——使用 pnpm 时，新增依赖永远用 pnpm add，同步依赖永远用 pnpm install。

2.5 常用进阶命令

• pnpm store prune：清理全局存储中未被任何项目引用的包。
• pnpm why <pkg>：查看某个包被引入的原因。
• pnpm list -g：列出全局安装的包。
• pnpm env use --global lts：使用 pnpm 管理 Node.js 版本。

2.6 从 npm / Yarn 迁移

1. 删除 node_modules 和旧锁文件（package-lock.json 或 yarn.lock）。
2. 安装 pnpm。
3. （可选）运行 pnpm import 生成 pnpm-lock.yaml。
4. 运行 pnpm install。

三、Monorepo 最佳实践

pnpm 内置了对 Monorepo 的原生支持，通过 Workspace 机制，可以在一个仓库中管理多个相互关联但独立的项目。

3.1 初始化 Monorepo

1
2

mkdir my-monorepo && cd my-monorepo
pnpm init

3.2 配置 pnpm-workspace.yaml

1
2
3
4

packages:
  - 'apps/*'
  - 'packages/*'
  - '!**/test/**'

3.3 配置根目录 package.json