某天开始，我的飞书机器人消息照收不误，但一条回复都发不出去。

根因不在我的代码、不在网络、不在凭证，而是飞书侧的一条未公开的访问控制策略：

用「豆包账号」身份登录的飞书账号，其名下自建应用只要配置了任何 OpenAPI 权限，在获取访问凭证（tenant_access_token）时就会被策略拒绝，返回未收录于官方文档的错误码 21001；而未配置任何权限的应用反而一切正常。换用手机号/邮箱注册的飞书账号建同权限的应用后，立即恢复。

这不是推测，是可以 100% 复现的实测结果（文末给了可复制的验证步骤）。

一、故障现象：一个反直觉的「半瘫」

出站返回的是：

1
2

HTTP 200
{"code":21001,"msg":"Access denied by access control policy. Contact the administrator for assistance."}

第一个关键信息就藏在这里：HTTP 状态码是 200。

不是超时、不是 5xx、不是连不上——请求稳稳到达了飞书并被正常处理，是飞书在业务层明确拒绝。这一条就把「网络问题」「防火墙」「DNS」全部排除掉了。

第二个关键信息：入站正常、出站失败。这个不对称非常有价值——它说明不是整个连接死了，而是某个只在 HTTP API 侧生效的检查没通过。

二、排查路径

第 1 步：先分清入站和出站

看网关日志：接收侧的长连接一直是稳的，发送侧每一条都在报同一个错误。故障定位于「出站 / 鉴权层」。

第 2 步：凭证对照实验（一分钟把「凭证错」排掉）

拿正确凭证和故意写错的凭证各打一次取 token 的接口：

结论很干净：飞书是先校验凭证、再走策略的。既然正确凭证没报「凭证无效」而是报「策略拒绝」，说明凭证是对的，卡点在策略层。

（这也说明：任何「重置 App Secret」的操作对本故障都是无效的——我确实也试过，白费一轮。）

第 3 步：21001 到底是什么？

这是整个排查最难受的部分——官方查不到：

• 飞书官方的《通用错误码》列表里没有 21001；
• 官方站内搜索 21001，国内站和国际站都是 0 结果；
• 客服渠道问了一圈，没有有效回复。

唯一的官方线索来自飞书官方 CLI 的源码：

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

const (
    LarkErrBlockByPolicy        = 21001 // access denied by access control policy
    LarkErrBlockByPolicyTryAuth = 21000 // ……challenge is required to be completed by user
)

// SecurityPolicyError is returned when a request is blocked by access control policies.
type SecurityPolicyError struct {
    Code int
    Message string
    ChallengeURL string
    CLIHint string
    Err error
}

也就是说：这个码属于「安全策略类」，不是凭证错误、不是权限不足、不是频率限制。而且官方还在这条错误上预留了一个「验证/申诉入口」（ChallengeURL）字段——只是从没写过它什么时候会被触发。

第 4 步：★ 我在这里踩了一个大坑（把结论带偏了一天）

我当时的设计是：在同一个账号里新建一个「什么都没有」的裸应用，和出故障的原应用做对照。

结果非常好，好到让我错了：

据此我得出了结论：「这个账号没问题，是我这个应用被单独限制了」——然后沿着「应用被限制」的方向查了一整天，毫无进展。

第二天我才意识到问题出在哪：那个「什么都没有」的裸应用，恰好绕过了这条策略。

教训：对照组选错，得到的结论比没有结论更危险。
这里的变量其实有两个——「账号身份」和「应用是否持有权限」。用空权限的应用去做对照，等于同时把这两个变量都改了，看起来找到了差异，实际是把真正的变量藏了起来。

第 5 步：二维对照实验，定案

重新设计对照：账号 × 应用权限，两个维度都取到：

只有「账号 A + 带权限」这一格是红的。

把它拆成可验证的断言：

• 同一个账号下，空权限应用通过、带权限应用被拒 → 不是「账号被封」，是权限维度的策略评估；
• 同一个权限配置下，账号 A 被拒、账号 B 通过 → 不是「应用有问题」，是账号身份维度；
• 两者在同一时刻、同一台机器、同一出口 IP、同一客户端上测的 → 源 IP、网络、客户端全部无关。

我随后又独立跑了两轮复核：8 次调用 8 次一致，零抖动。

三、可复制的验证步骤（约 2 分钟）

如果你怀疑自己遇到了同一条策略，可以这样验证。准备两个应用：一个随便加两个权限，一个什么都不加，然后用同一个账号的凭证分别请求：

1
2
3

curl -s -X POST 'https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal' \
  -H 'Content-Type: application/json' \
  -d '{"app_id":"{你的_app_id}","app_secret":"{你的_app_secret}"}'

预期结果（如果你也在被拦）：

第三行是关键的对照组：如果错误凭证能拿到「凭证无效」而正确凭证拿到「策略拒绝」，那就说明你的凭证没问题，问题在策略层。

排查时注意把飞书返回的 x-tt-logid（请求追踪 ID）留存下来——它是唯一能向官方定位这次调用的凭据。

四、能查到的和查不到的

官方侧存在、但不点名的信号：

• 飞书开放平台 changelog，2026-07 下旬：「Agent 访问官方接口时增加账号保护：保护策略默认开启，只对飞书或 Lark 官方接口生效」
• 飞书开放平台 changelog，2026-10 上旬：「登录、获取凭证和身份验证遇到安全策略拦截时，保留服务端返回的提示、验证入口和规则信息」

查不到的：

• 21001 的官方定义、触发条件、解除方式
• 开发者后台里没有任何提示：没有站内信、没有邮件、没有横幅、没有违规通知
• 「豆包账号登录飞书后……此类账号没有企业管理后台」——这意味着这类身份连「去哪改设置、去哪申诉」的入口都不存在

同期社区里有其他人中招： 2026-10-13 前后，飞书官方仓库的两个 issue（larksuite/cli#2815、larksuite/openclaw-lark#639）以及若干技术论坛帖，记录的是同一个现象：入站长连接正常、出站全部 21001、无效凭证返回的却是另一个错误码。其中一条 issue 的标题直接点名了账号类型，评论里也有多位「豆包账号」用户报告同样的失败。

需要说清楚的一点： 以上是我能实测到的行为，不是官方说法。飞书至今没有就这条策略发布任何公告，本文不对其动机做任何推断——我只陈述可复现的事实。

五、如果你也遇到了：判别手册

第一步：把入站和出站切开。
长连接正常 + HTTP 全挂 → 问题在出站/鉴权层，不是网络。

第二步：看错误码定性。

第三步：做凭证对照实验。（见上文，一分钟出结论）

第四步：做二维对照实验——这是最关键的一步。

1
2
3

             带权限的应用   空权限的应用
账号 A          ？            ？
账号 B          ？            ？

• 只有换账号才好 → 账号身份维度
• 只有空权限应用能通 → 权限维度
• 千万别只用空权限应用做对照，它会给你一个看起来完美、实则错误的答案。

第五步：留存证据找官方。 记下 app_id、tenant_key、完整响应体、x-tt-logid。21001 未文档化，一线客服大概率无解，需要真正到 oncall 才能定位。

六、三条教训

1. HTTP 200 + 业务错误码 ≠ 你的代码有问题。 当状态码成功而业务码异常时，要立刻把怀疑方向从「我的实现」转向「中间的策略层」。
2. 对照实验的对照组选错，比没有对照更危险。 我因为一个「空权限的裸应用」，得出「只有我的应用被限制」的结论，白查了一整天。控制变量必须同时锁住你怀疑的每一个维度，哪怕这意味着多建两个应用。
3. 平台静默变更 + 未文档化错误码，意味着你只能靠可复现实验自救。 这类故障里，社区里别人的复现记录（issue、论坛帖）往往比官方文档更有用——因为文档里根本没有这个东西。

顺便说一句：这次故障从发生到被发现静默了 17 小时——期间机器人一切看起来都在正常「工作」，只是所有回复都发不出去。如果这类链路对你重要，值得加一条主动健康检查，而不是等用户告诉你「你怎么不回我」。

后记

我已经把应用迁到手机号/邮箱注册的飞书账号上，收发恢复正常，并把整套判别流程记进了自己的运维笔记。

写这篇的目的很简单：这条策略是静默生效的，官方既没有公告也没有文档，遇到的人大概率会先怀疑自己的代码、网络或凭证，然后在「重置密钥」这种无效操作上耗掉大半天。如果这篇能让你在 10 分钟内定位到「是策略层」，那就值了。

成品在这里：https://nova02640.github.io/ai-engineering-quest/

一、选题：先确认”不该做什么”

项目起点是一套很对我胃口的开源课程：AI Engineering from Scratch，523 课、20 个阶段、每课都要求你手写一遍算法并留下一个可复用产物。

我最初的想法和大多数人一样：做个学习网站。但动手之前先去读了上游仓库，结论立刻变了——上游已经有一个功能完整的网站：523 课在线渲染、每课课后小测、本地进度记录、交互式图表、术语表、学习路径、认证备考题库、12 种语言界面，而且仓库每天都有提交。

如果我照着做，结果只会是两个问题：功能更少，且要永远追着上游跑。

于是任务定义从”做一个学习网站”改成了”做一个上游没有的东西”。 把上游的功能清单逐条列出来对照之后，剩下的空白很清楚：

定位就这么定下来了：不做课程，做课程的记录层。

二、架构：薄层，而不是镜像

第二个决定同样重要：课程正文一个字都不进我的仓库。

站点只取元数据——标题、序号、路径、类型、语言、学习目标、outputs/ 与 code/ 的文件清单；所有阅读和练习深链到官方原文。

这样做的代价是站内阅读体验不完整（要跳出去看讲义），换来的是：

• 维护成本极低：上游每天改正文，我的站不受影响
• 版权性质完全不同：引用元数据 + 深链是工具；搬运全文是转载
• 可一键切割：上游若改许可，删元数据即可

页面结构也随之变得很轻——四个静态页 + 一个本地存档引擎：

1
2
3
4
5
6
7

index.html        闯关地图（20 阶段 / 523 关 + HUD）
lesson.html       关卡页（四步打卡 / 小测 / 作品登记）
boss.html         阶段 Boss 关（12 题）
portfolio.html    作品集（导出 HTML / Markdown / JSON）
assets/store.js   存档引擎（localStorage + 导入导出）
data/course.json  523 关元数据
data/quiz.json    题库

没有构建步骤：纯静态文件直接由 GitHub Actions 上传，失败面比任何构建型站点都小。

三、数据管线：只取我需要的字段

元数据分两层拿：

全量地图（20 阶段 / 523 关）：用 GitHub Tree API 一次拿全量文件路径，从路径推导出阶段与关卡结构；再解析上游 README.md 里的关卡表格，拿到每关的标题、类型（Learn / Build）和语言。523 关里有 438 关能从表格解析到，剩下的 85 关全是最后的 capstone 阶段（不在表格里），用路径名兜底即可。

深做阶段的细节：只为要深做的那个阶段逐关取 docs/en.md，提取一级标题和 ## Learning Objectives 列表。31 关约 492 KB，几十秒拿完。

这里有个小取舍值得一说：我一度想直接下整个仓库的压缩包，但网络受限环境下镜像通道给的包是截断的（两次分别拿到 9.2MB 和 4.6MB，都不是完整包）。与其和下载较劲，不如只取真正需要的字段——31 个小文件的元数据，比 46MB 的整仓依赖更可靠。

四、玩法：口径要照抄课程，不要自创

游戏化的诱惑是自创一套规则（经验值、等级、成就系统随便设计）。但这里有个约束：这套课程自己已经有一套明确的方法论——读 → 写 → 跑 → 存证，而且它的讲义里就是把 evidence 当成学习闭环的终点。

所以我把关卡的通关口径直接映射到这四步，而不是另造一套：

每 250 XP 一级；阶段全部通关解锁 Boss 关（12 题，通过线为三分之二）；证据登记进作品集，可导出。

规则贴合课程本身，用户就不需要在两套心智模型之间切换——这是我在这个项目里最满意的一个决定。

五、验证：让”我觉得能跑”变成”实测能跑”

前端项目最容易糊弄自己的地方是：打开页面点两下，觉得没问题，就发布。 这次我给自己定了四条硬规矩。

1. 用 Node 在服务器上真跑前端逻辑

纯前端逻辑通常是”要开浏览器才能测”的，但其实只要把浏览器环境 stub 掉，就能在服务器上直接跑：

1
2
3
4
5
6
7
8
9
10
11

// tools/test-store.mjs 的核心几行
globalThis.localStorage = {
  getItem: (k) => (k in mem ? mem[k] : null),
  setItem: (k, v) => { mem[k] = String(v); },
  removeItem: (k) => { delete mem[k]; }
};
globalThis.window = globalThis;

new Function(fs.readFileSync('assets/store.js', 'utf8'))();   // 真跑业务逻辑
const Store = globalThis.Store;
// 然后直接断言：通关判定、XP 计算、徽章、导入导出……

这套 39 条断言的回归测试，抓出了一个真 bug：

原来的通关判定，是靠”这一关有没有作答记录”来判断它有没有题库。于是出现了一个荒诞的结果——有题库的关卡，只要一道题都不答，四个勾打完就算通关。题库门禁形同虚设，而且从界面上完全看不出来（四勾显示完整、状态显示已通关）。

修法是让加载层把题库索引显式注册给存档层，判定优先级变成「注册索引 > 本机作答记录」：

1
2
3
4

function hasQuizFor(path, l) {
  if (Object.prototype.hasOwnProperty.call(quizIndex, path)) return quizIndex[path] > 0;
  return !!(l && Object.keys(l.quiz).length);   // 退化路径：本机是否作答过
}

这个 bug 不写测试是发现不了的——它只在”用户从不答题”这条路径上出现，而开发者自己测试时一定会去点那两道题。

2. 数据一致性测试

第二个测试文件专门校验数据：题库的每个 key 都是真实关卡路径、每关题目数量、ID 唯一性、选项数、答案下标范围、题干语言、以及课程数据与题库的对应关系。480 条断言，全绿才允许提交。

3. 线上逐字节校验，并识别”截断误报”

部署完的验收不能只看首页 200。我的做法是把关键文件在线上取回来，和本地比 sha256。

第一次校验就出现了一个可疑数字：data/course.json 线上读到 99681 字节，本地是 162046 字节。

看起来像产物损坏，但这其实是 CDN 单次传输截断的经典指纹。判定口径有三条：

• 连续多次取回，看大小是否每次都不一样（截断的特征）
• wget -c 续传后比对 sha256
• 用 curl -r 0-0 -D - 读响应头的 content-range: bytes 0-0/162046，直接拿到真实总长

复核结果：重取四次全部 162046 字节，sha256 与本地完全一致，JSON 也解析正常（20 阶段 / 523 关都在）。问题在取数，不在产物。 如果当时直接下结论”文件坏了”，就会白查一轮。

4. 不要相信”子代理”自报的数字

题库我拆成三个并行的 AI 子任务分工出题，每个任务完成后回报：”共 26 题 / 24 题 / 20 题”。

合并前我按 schema 自己复算了一遍：实测是每关正好 2 题，总共 62 题。

三个数字全是错的（它们把自己的计数算重了）。如果我直接引用自报数字写进 README，就会把一个假数据固化进项目文档。凡是子任务交付结构化数据，合并前必须自己复算：覆盖度、条数、唯一性、字段范围，一个都不能省。

六、版权与边界

上游是 MIT 许可，允许复用，但”允许”不等于”可以随便抄”。这个项目的处理是三件事：

1. 署名齐全：仓库 ATTRIBUTION.md + 站点页脚 + 首页「关于」区，三处都写明上游仓库、作者、MIT 许可原文
2. 零正文镜像：只引元数据，深链原文，不复制图表、图片、界面文案
3. 不冒名：不使用上游的名称和 Logo 作为自己的品牌（MIT 覆盖代码，不覆盖商标），并明确声明本项目与上游没有官方关系

另外一个细节：题库是我自己出的（上游的随堂测验是运行时生成的，没有静态题库）。出题依据是公开讲义，但题目和解析都是转述，不是抄录。合并前我做了一次机械检查——把每道题的文本和讲义原文做”连续 N 字符重合”扫描，命中的三处全部是英文 API/代码片段（函数签名、HTTP 响应头这类），属于必须原样出现的技术术语，不是复制正文。

七、隐私与安全：写公开技术文章的自律

这篇是开发记录，很容易顺手写出不该写的东西。发布前我按清单逐项过了一遍，规则是：

不出现的：

• 内网 IP、主机名、机器别名
• 内部存储路径（挂载点、卷目录这一类）
• API key / token / 密钥 / 任何服务凭据与访问链接
• 内部工具名、任务日志、会话内容

泛化处理的：

• 环境叙述只说”一台内网 Linux 主机””服务器”，不写型号、地址、主机名
• 涉及网络受限时，只描述方法与结论（走哪个 API、为什么选小文件而不是整包），不写代理方案细节
• 配置示例一律用占位符（<token>、<host>），绝不贴真实值

顺手做的一次历史检查： 我扫了一遍已发布的老文章，确认此前写过的网络类文章里只有通用配置，没有凭证、服务地址或内网信息——没有泄露。这个检查值得定期做，因为”当时看起来无害的配置片段”，很多是事后才意识到敏感的。

八、反思

做对的两件事：

1. 先查上游再动手。如果一开始就闷头做”学习网站”，两天的成果就是一个注定要废弃的镜像站。
2. 口径照抄课程。不自创规则，用户不需要在两套心智模型之间切换。

做得不够的一件事：

形态这件事，我其实是先做完再给使用者看的。更省钱的做法是先做一个阶段的小样（一个阶段 20~30 关，真实内容 + 完整交互），确认形态和信息密度之后再铺量——这个项目里我只深做了一个阶段就停手，还算踩在线内，但下一个项目我打算把这个顺序固定下来。

小结

如果你也在做同类项目，这篇里最值得拿走的大概是两条：

• 上游已经有的，不要重做；把上游的功能清单列出来，差异化的空间自然浮现
• 纯前端逻辑也可以有真回归：stub 掉浏览器环境，在服务器上跑断言，它救我的那一次就是最好的理由

站点：https://nova02640.github.io/ai-engineering-quest/

我把一套 523 课的 AI 工程开源课程，做成了一个能”闯关”的进度站：

• 站点：https://nova02640.github.io/ai-engineering-quest/
• 仓库：https://github.com/nova02640/ai-engineering-quest

它不是课程的重做版，而是给课程补上进度感和作品感的那一层。全文讲清楚三件事：这套课程是什么、这一层补了什么、以及它为什么刻意不搬运任何课程正文。

这套课程本身，值得认真对待

课程是 AI Engineering from Scratch（作者 Rohit Ghumare，MIT 许可）：

它最大的特点是**”先手写、再用库”**：每个算法都要求你从原始数学推一遍（反向传播、分词器、注意力、Agent 循环），等你用上 PyTorch 的时候，已经知道它在底下做什么了。

这套课程自带一套很硬的方法论，讲义里把它写成了四步循环：

读 → 写 → 跑 → 存证
（read / built / ran / evidence）

问题也恰恰在这里：523 课不是一次能学完的东西，而课程本身没有给你一个”我走到哪了”的全局视图。你学完一关，成就感只存在于当天的终端输出里。

所以我没有做”学习网站”

先把一句话说清楚，因为它决定了整个架构：

上游已经有一个功能完整的学习网站了。 官方站有 523 课的在线渲染、每课课后小测、本地进度记录、交互式图表、术语表、学习路径、认证备考题库，还有 12 种语言的界面。

所以如果我再做一个”学习网站”，那只会是一个功能更少、且要永远追着上游更新的镜像。这不是产品，这是负债。

上游真正空着的是这两件事：

1. 进度的全局感：官方进度是每课四个勾选框。有勾选，但没有”我打到第几关了””这个阶段离通关还差多少”这种闯关视角。
2. 证据留不下来：官方那一步叫 evidence，但实际只记录了一个”已勾选”的时间戳——你当时跑了什么命令、退出码是多少、产出了什么文件，都没有地方存。

而作品这件事，恰恰是这套课程反复强调的：”Every lesson ships a reusable artifact.”——每课都交付一个可复用的产物。课程这么说，却没有帮你把这些产物收集起来。

于是这个站的定位就很清楚了：不做课程，做课程的记录层。

这一层具体是什么

一、闯关地图

20 个阶段、523 关全部列出来，每关是一张卡片，四个小格显示四步的完成情况，颜色区分「没开始 / 进行中 / 已通关」。顶部是等级、XP、总进度和徽章数。

二、关卡页：四步打卡 + 小测 + 作品登记

每一关有：

• 四步打卡：读 / 写 / 跑 / 存证，口径完全照抄课程自己的方法论
• 一键跳原文：官方讲义页和 GitHub 源码目录，你不用在站内找路
• 关卡小测：一概念一实践两道选择题，答对立刻给解析
• 作品登记：命令、退出码、关键输出、产物位置、一句话心得

关卡页还会根据关卡语言自动给出建议运行命令（Python 给 python3 ...，TypeScript 给 npx tsx ...），直接复制就能跑。

三、Boss 关

每个阶段清完之后，解锁该阶段的 Boss 关：12 道综合题，覆盖这一阶段的不同关卡，答对 8 题（三分之二）算通过，通过得一枚阶段徽章。徽章不会因为之后刷低分被撤销。也可以提前挑战，只是会提醒你还有几关没通。

四、作品集

所有登记过的证据会汇成作品集，按阶段聚合，并且可以一键导出：

• 单文件 HTML：自带样式的独立页面，可以直接发给别人或丢到任何地方
• Markdown：适合贴进博客、周报
• JSON：存档，用于跨设备同步

进度存在浏览器本地（localStorage），不上传任何数据；换设备就导出 JSON 再导入。

玩法口径（照抄课程，而不是自创）

每 250 XP 升一级。有题库的关卡，必须至少答对一题才算通关——四步全勾但不能白嫖（这条规则背后有个真实 bug，我在开发记录里写了）。

边界：只取元数据，不搬运正文

这是这个项目最重要的一个决定。

站点用到的课程信息只有：关卡标题、序号、路径、类型（Learn / Build）、语言、学习目标、outputs/ 和 code/ 的文件清单。所有阅读和练习都指向官方原文——站内没有一个字的讲义正文，也没有复制上游的图表、图片和界面文案。

这么做有三层好处：

1. 版权上干净：MIT 允许复用，但”引用元数据 + 深链原文”和”整站镜像正文”是两件性质完全不同的事。前者是工具，后者是转载。站点页脚、关于区和仓库的 ATTRIBUTION.md 三处都写明上游作者与许可，也不沿用上游的名称和 Logo 做自己的品牌。
2. 不用追更新：上游仓库每天有多次提交。我只依赖元数据，所以上游改正文，这个站不会失效。
3. 可一键切割：万一上游改许可或对引用方式有异议，删掉对应的元数据就行，站点不会塌。

站内题库是我自己出的（上游的随堂测验是运行时由 AI 现场生成的，并没有静态题库），出题依据是公开讲义，题目和解析都是转述。

现在能用到什么程度

说清楚当前状态，避免误解：

• Phase 13（工具与协议，31 关）是深做的：有学习目标、有每关小测（62 题）、有 Boss 关题库（12 题）
• 其余 19 个阶段是元数据模式：关卡清单、类型、语言齐全，可以用四步打卡通关，但没有小测和 Boss 题库

也就是说，除 Phase 13 之外的阶段，你能用它看进度、打勾、登记作品，但不能答题闯关。要不要把题库铺满 20 个阶段，我打算先看自己实际用一段时间的感受再决定——这种项目最容易犯的错，是一口气把全量内容铺完，结果发现形态不对，全部沉没。

怎么上手

1. 打开 https://nova02640.github.io/ai-engineering-quest/
2. 点开 Phase 13，从第一关开始，先点「官方讲义页」把这一课读完
3. 手敲代码、跑通、回到关卡页把四步勾上、答完小测、登记一条证据

就这样。523 关很长，但至少现在，你能看见自己走到哪了，也能把走过的路拿出来给人看。

声明

这是一个独立个人项目，与上游作者和课程官方没有任何隶属或背书关系。课程内容、课程名称与原始讲义的一切权利归原作者 Rohit Ghumare 所有（MIT 许可）。本站代码同样以 MIT 发布。

如果上游作者认为本站的引用方式有任何不妥，通过仓库 Issue 联系，我会立即下线相关内容。

之前写过 DeepSeek Harness（dsh）的架构拆解和真实任务实测，当时的结局是：能用，但在快速迭代期没留下，我把它清掉了。

这次它以另一种形态回来——官方发布了 Python SDK，而且宣传点很具体：会话状态、用会话 UUID 复用上下文来省 token。

这个点正好戳中日常委托编码任务的痛点：每次让代理干活都从零开始，同一份上下文反复付费。于是我没有直接采信，而是搭了一套可复现的对照实验，把它和我日常在用的 OpenCode 拉到同一张考卷上。

结论先说：同题两轮小任务，两边都真做对了，dsh 略快略省；换成三轮递进的大任务，dsh 默认反而慢 1.5 倍、贵 3 倍。而”会话复用省 token”这件事，只在同一个进程内成立——那条最诱人的卖点，被我实测卡掉了。

下面是完整的取证过程。

一、先分清：这是另一条通道

第一件事是别把新旧两次部署搞混。它们虽然都叫 dsh、都用同一个模型，但形态完全不同：

有个细节值得一提：PyPI 上存在一个同名无关包叫 deepseek-harness，纯粹是蹭名字的；官方的是带 -sdk / -runtime-bin 后缀那两个。选包时认准作者和仓库链接。

SDK 的本质是子进程驱动：DeepSeekHarness(...) 在后台拉起打包好的 dsh --profile <profile>，然后通过 stdio 上的 JSON-RPC 通信。所以它并不是”一个新的 agent”，而是同一套 agent 的程序化接口——真正变的，是打包方式和你能拿到多少控制权。

顺带一个实打实的优点：每次调用的 token 用量可以从事件流里取出来（输入 / 缓存命中 / 输出 / 思考 token 分列），这让成本可以精确核算，而不是靠感觉。

二、能不能装：环境门槛与一个真实的坑

官方给的门槛不高：64 位 Linux、glibc ≥ 2.28、Python ≥ 3.10。我手头那台内网 x86 Debian 小主机是 glibc 2.41 + Python 3.13，全部满足。

真正的坑在网络上：

• PyPI 直连被重置（curl: (35) Recv failure: 连接被对方重置），而且不只是索引页——大文件下载会在中途断流（实测下到 452KB 就断）。
• 解决办法是换镜像源，一次装完。顺带发现系统 Python 不自带 pip，得先补一个 python3-venv 包。

装成之后的体积：虚拟环境约 290MB，其中绝大部分是那个274MB 的原生运行时单文件；此外每个工作目录一份的 harness home 只占几 MB。

凭据处理上沿用了一贯做法：API key 通过环境变量注入，不落盘。冒烟测试 3.9 秒返回预期输出，退出状态正常。

⚠️ 一个必须说清的风险：当前版本是 0.1.5-rc.1，属于 release candidate，官方明确声明会有破坏性变更，迭代速度极快。选它做生产依赖要接受这个前提。

三、怎么测才算数：把”感觉”换成”判据”

在讨论”效果好不好”之前，得先解决一个问题：我们凭什么相信结果？

搞过编码代理的人都知道，这类工具最大的风险不是”做不出来”，而是**”说自己做出来了”**。之前实测里就见过”报 Done + 退出码 0，产物其实不可用”的情况。

所以这次我把评估搭成了这样：

1. 每个任务都自带验收闸门：一份可执行测试脚本，通过对 / 不通过是二值的。
2. 期望值靠”预埋答案”生成：先自己写一份参考实现，用它算出期望值写进闸门——而不是让被测对象自己说”我算对了”。
3. 闸门本身先验证：参考实现必须 100% 通过闸门，空实现必须全挂。两者都成立，判据才算有效。（这一步经常被跳过，但它是整个评估的地基。）
4. 同种子、同 prompt、同验收文件的隔离工作区：两个候选各拿一份完全相同的副本，互不污染。
5. 验收文件哈希校验：跑完之后比对验收脚本和期望值的哈希，确认没被篡改——防止”改测试来通过测试”。
6. 所有闸门由我亲手复跑，不看代理的自述。

这套流程后来被证明是值得的：本轮的每一个结论都建立在”我自己跑出来的绿灯”上，而不是任何一句自我汇报。

第一个任务很小：一个购物车计价模块，我植入了三处 bug（档位边界用了 > 而非 >=、金额用向下取整而非四舍五入、优惠券在税后扣且没做零下限），要求修好使 9/9 用例通过。基线确认：植入 bug 的版本 0/9 全挂，判别力足够。

四、第一个反直觉发现：会话复用只在同一个进程里成立

这是整轮评估最关键的结论，也是我被”宣传点”误导的地方。

同一个进程内：有效，而且收益明显

在一个进程里用同一个会话连着做两轮（第一轮修 bug，第二轮在已经改好的代码上追加一个新函数）：

对照组是”同样的第二轮任务，但开一个全新会话”：需要 7,87812,715 新鲜输入 token、3145 秒。

也就是说：续用会话让新鲜输入降到约 1/4.6，耗时降到约 1/6。宣传里说的收益，在这个范围内是真的。

跨进程：被明确拒绝

问题来了。真实的自动化场景里，任务不是在一个长进程里跑完的——每次委托往往是一次独立的调用。于是我试了在新进程里复用同一个会话 ID：

1
2
3

h.run(prompt, session_id="...")        → JsonRpcError: session "..." already exists
h.start_session("...").run(prompt)     → JsonRpcError: session "..." already exists
删掉会话锁文件后重试                     → 同样报错（不是残留锁的问题）

再往下探，直接问底层 RPC：

1
2
3

session/list   → unknown DeepSeek Harness SDK runtime method
session/resume → unknown DeepSeek Harness SDK runtime method
session/load   → unknown DeepSeek Harness SDK runtime method

而用 strings 翻那个 274MB 的运行时二进制，session/resume、session/load、session/list 这些符号明明存在——它们属于 CLI 那一侧的完整表面，只是 SDK 运行时把这条路封掉了。

结论很清楚：SDK 的会话对象只在一个 harness 进程的生命周期内有效。磁盘上那些 JSONL 会话日志是审计 / 重放用的，不是可续用的检查点。官方文档那句“复用 harness、home 和 id 来延续同一段对话”，真实含义就是这个限定范围——但它太容易被读成“随时可以续上”。

那对照组的 OpenCode 呢？

同样的问题抛给 OpenCode（它支持 --session <id>）：新起一个进程，不读任何文件，仅凭会话历史回答”上一轮你新增的函数叫什么”——

1
2

> build · deepseek-v4-flash
`summaryText`，内部调用了已有的 `total` 函数。

答对了。所以在这个具体维度上，我一直用的 OpenCode 反而是更强的一方。

五、顺手抓了一次包：请求里到底发了什么

既然已经装好了，我顺手做了一件平时容易忽略的事：把 SDK 的请求指向一个本地 mock 端点，把原始请求体抓下来看。

（方法很土但有效：起一个假的 OpenAI 兼容接口，把收到的 body 落盘，再返回一段合法的流式响应。）

抓到的请求顶层字段：

1
2

dsh_plugin_packages, max_tokens, messages, model,
reasoning_effort, stream, stream_options, thinking, tools

两点发现：

• ✅ 默认不上传会话日志——请求里没有 dsh_session_log 字段。有意思的是，官方两份文档对此说法互相矛盾（一份说默认关闭，另一份的教程说默认会上传未接受的日志后缀）。以实测为准：默认不发。想彻底排除可以在 profile 配置里显式关掉。
• ⚠️ 但每个请求都会带一个 dsh_plugin_packages 字段，约 1.8KB，内容是插件名 + 版本清单。它不是对话内容，但确实是把本机环境信息随请求发出去了。

另外两个默认值也值得知道：默认开启 thinking，且 reasoning_effort 默认是 high。这个默认值，在第七节变成了钱。

六、把短板补上：一个常驻 worker 原型

既然裸 SDK 的问题是”会话活不过进程”，那答案就很直接：让进程活着。

我写了一个小原型：

• worker：常驻服务，监听 Unix socket，按 (profile, 工作区) 复用 harness——同一个工作区复用同一个 harness 进程，不同工作区各起一个；同一 harness 串行、不同 harness 并行；对外提供 run / ping / sessions / shutdown。
• client：一个极瘦的客户端，一个进程发一个请求，用完即退。会话由 worker 持有。

这样一来，”调用方进程”和”会话持有者”解耦了。实测三个完全独立的客户端进程共用一个会话：

worker 日志确认 harness 只启动了一次（2.3 秒），后面全部复用。第 3 次调用几乎不花输入 token——因为它要的东西全都还在缓存里。

这就是那个缺失能力的补法：不指望 SDK 支持跨进程，而是自己维护一个长期活着的进程。这个思路对所有”启动成本高、会话有状态”的 CLI 代理都通用。

七、换大任务再测：数字翻转了

小任务上两边旗鼓相当，我不放心——小任务跑得好，不代表大任务跑得好，这几乎是我对这类工具最深的偏见来源。所以第二轮我做了一个真实一点的任务：

一个空白 Node 项目，分三轮递进交付：

1. 写一个脏 CSV 解析器（要处理 BOM、CRLF、引号内的逗号和换行、"" 转义、空字段补位、末尾空行）
2. 在解析器之上做分组聚合（count / sum / avg / min / max、空值边界、分组排序）
3. 再做命令行入口（复用前两个模块、三种错误退出码、单行 JSON 输出）

每一轮配一个独立闸门（分别 3、4、10 项断言），期望值同样由参考实现预埋生成。

两者都真做对了——三轮闸门全绿，交付物规模相当（各约 150~190 行有效代码）。但代价完全不同：dsh 默认慢 1.5 倍、贵 3.1 倍。

钱花在哪儿了

翻 token 明细就一目了然：dsh 的总输出 token 是 22,831，其中 17,619（77%）是思考 token；OpenCode 同任务输出只有 4,200。前三节里那个”默认 reasoning_effort: high“，在这里变成了账单。

把 reasoning_effort 调成 low 之后：成本降 48%（$0.0160 → $0.0083），质量不掉（三轮闸门照样全过），但仍然比 OpenCode 贵 1.6 倍、慢 1.4 倍。

成本是怎么算的（顺便验证了口径）

dsh 不上报美元金额，只给 token。所以我用官方公布的单价（缓存命中 / 未命中 / 输出三档）自己算。为了确认口径没错，我拿 OpenCode 自报的成本做了反向对账：

按公布单价的”谷值”档计算 → 得到 $0.0052，与 OpenCode 自报的增量成本完全一致。

这说明两件事：单价格式选对了，以及在便宜时段跑确实能拿到折扣价。先验证计算口径，再相信计算结果——这一步比计算本身更重要。

八、经验与结论

1. 自报永远不算数，判据要先于结论。
这轮所有绿灯都是我亲手跑出来的：闸门先被参考实现和空实现双向验证过，跑完再核对验收文件哈希。这个过程不浪漫，但它把”感觉它做得不错”换成了”它确实通过了这 17 项断言”。

2. 成本要看 token 结构，别信”印象便宜”。
同一对候选，在小任务上成本几乎一样（$0.0027 vs $0.0029），换到大任务就差 3 倍。原因不是”谁更笨”，而是默认参数把预算导向了思考过程。任何”某工具更省钱”的结论，如果没拆开输入 / 缓存 / 输出三档看过，都不值得采信。

3. 要区分”被测对象失败”和”测试装置失败”。
这轮我犯了两次滑稽的错误：一次是给被测程序的 prompt 用了相对路径，工作目录一变就找不到文件，于是三轮全部”失败”；另一次是后台跑对照组的命令行时漏注入了 API key，它 10 秒就退出——我第一反应是”这工具怎么这么差”，差点把这个当成结论写进报告。

教训很明确：代理秒退、零产出、耗时异常短，这些首先应该怀疑测试装置，而不是被测对象。 我把这条写进了自己的操作手册。

4. 关于那个常驻 worker 原型。
它是这轮里我最满意的产出：不算复杂，但把”会话复用”从”进程内的特性”变成了”可跨调用的服务”。它也说明了一件更普遍的事——当工具有个你不喜欢的限制时，先看看是不是能在外面绕过去，而不是立刻放弃它或者接受它。

5. 最终结论：不替代，且已清理。
综合下来我没有保留它：

• 它的核心卖点（会话复用省 token）在跨进程场景下不成立，我补的 worker 补上了这个能力，但对照组原生就有；
• 大任务上它默认更慢更贵，要显式调参才能追到 1.6 倍差距；
• 版本还是 rc，官方声明会有破坏性变更。

它剩下的独特价值只有两处：逐次调用的 token / 缓存 / 结束原因可以编程取数（适合做计量与风控），以及不依赖 Node 的干净部署——这两个场景我暂时用不上。

所以评估做完，环境清理干净，回到原来的方案。

尾声

这轮下来，我真正收获的不是”哪个工具更好”的答案，而是一套可以重复使用的评估姿势：

先写参考实现，用它验证判据；再跑对照，用判据验收产物；最后拆开 token 明细看钱花在哪；并且时刻准备怀疑自己的测试装置。

工具会一直换，这套姿势不会。

封面图：Wikimedia Commons，English weight with calibration stamps，CC0（公有领域献出），摄影 HelgeRieder。选它是因为——评估的根本，是先有一个可信的标准参考物。

上篇《DeepSeek Harness 深度调研》是从源码与文档出发的纸面拆解。这篇不一样——把 dsh 拉到真实任务里跑了一遍：部署、小任务基准、最后让它从零写出一款可玩的仙侠回合制页游，全程只做协调与验收，不碰它的代码。

结论先说：任务完成了，游戏在线可玩（文末有链接），过程中没有出现某些第三方评测里”报成功但产物损坏”的假成功；但暴露了一个现实约束——单轮任务时长不够大项目，需要分轮续写协作。

一、评估：部署到内网小主机

测试环境是一台内网 x86 Debian 小主机。dsh 本体是 Node.js 包（@deepseek-ai/dsh），npm 全局安装约 500+ 依赖包，官方推荐 npx 起 Web UI，但真正适合脚本化调用的是 headless profile：

1

dsh --profile headless "任务描述"   # 一次性任务：stdout 打印最终答案后退出

这个形态与 opencode run、Codex 的 -p 几乎同构——恰好是我平时委托第三方编码 agent 的标准姿势，天然适配”助手协调、agent 干活”的分工。

第一个坑：Node 版本。 README 只写”安装 Node.js”，没标最低版本。实际要求 Node ≥ 22.19 或 24（不支持 23.x）：在 Node 20 上安装能成功，运行即崩，两个硬错误——

• Promise.withResolvers is not a function（Node 22+ API）
• node:module 不提供 stripTypeScriptTypes（Node 22.18+/24 API）

把测试机的 Node 升到 v24 后一切正常。装完顺手验证了密钥处理：dsh 的凭据系统原生支持 DEEPSEEK_API_KEY 环境变量注入，密钥不用落盘，这在自动化调用里是很干净的安全实践。

二、基准：两个可复验的小任务

正式委托大任务前，先跑两个结果可客观验证的小任务（避免”你说完成了就信你”）：

两次都干净利落，单次成本估计不到 1 分钱（V4-Flash 本身便宜，加上 90%+ 的上下文缓存命中率）。这个阶段我还读了一批第三方实测，其中 AtlasCloud 的深度测评 最值得警惕：同一个前端任务跑 3 次，3 次都报 “Done” + 自信的验证清单，但打开产物 2 次是坏的——它用 node --check（只查语法）当”验证”，对 SVG 路径合法性一无所知。另外配置不当（模型条目只写 id、不声明 contextWindow/maxTokens）会让同一任务贵 3.5 倍，且这些关键字段藏在包 README 里而不是官方文档。

教训就一条：任何 agent 的自述都不足信，验收责任在调用方。这条对 opencode、Codex 同样成立，不是 dsh 独有。

三、实战：让它写一款仙侠回合制游戏

基准通过后，下达了真实任务——用单文件 HTML5 Canvas 实现一款类似《仙剑奇侠传》的像素风回合制页游：

• 640x480 俯视角地图（草地/树木/木屋/洞窟/池塘），方向键/WASD 移动
• 移动随机遇敌，回合制战斗：攻击 / 仙术 / 道具 / 逃跑
• HP（体力）/ MP（真气）/ 攻防 / 经验升级 / 存档
• 纯原生 Canvas，零外部依赖，一个 index.html 打开即玩

第 1 轮：580 秒超时，产出 30KB 高质量骨架

任务跑了 580 秒被我设的 timeout 截断。检查产物：地图生成与绘制、角色移动、精灵、背包都写完了，代码结构干净、注释规范、语法零错误——但文件末尾留着一个 /*==PART_B==*/ 占位符，战斗系统、对话、主循环还没动。

这里值得表扬：它没有谎报完成。超时前它正在继续写，截断状态一目了然——这就是”诚实”的工程表现，与第三节提到的”假成功”形成鲜明对比。

第 2 轮：891 秒超时，主体完成 93KB

第二轮指示很克制：”在 PART_B 标记处继续补完，先通读现有代码、不要重写 Part A、完成后自检语法”。它正确衔接到已有代码，把场景状态机、回合制战斗、对话框、标题/结局全部补上，文件从 30KB 长到 93KB。中断时它正在跑自测（日志显示”标题→地图转换已通过，正在跑完整测试”）。

验收：没有浏览器，就把游戏真的”跑”起来

两轮都超时，产物到底能不能玩？光看代码不够。我用 Node 写了一个 DOM-stub 模拟器：用 vm 注入假 canvas/document/localStorage，加载真实游戏脚本，再塞一个探针读取内部状态（当前场景、战斗对象、血量），按状态机自动按键——标题选”新的旅程”→ 地图随机游走 → 遇敌进战斗 → 菜单按确认攻击 → 直到胜负结算。

模拟结果：

1
2
3
4
5

BOOT OK（无加载错误，数千帧随机按键零异常）
标题 → 地图（20 帧进入新游戏）
716 帧时随机遇敌，进入战斗
战斗胜利 → 转场回地图 ✓
第二次模拟：战斗失败 → 半血复活（HP 130→65，精确等于 maxHp×0.5）→ 回到木屋前 ✓

胜负两条通路都端到端验证通过，连”失败后扣半血复活”这种细节都和设计一致。中途模拟器还误报过一次”胜利后战斗对象为空”——查代码发现是场景渐隐转场的正常时序，虚惊一场，修正模拟器继续推进即可。

四、成果

• 试玩：https://nova02640.github.io/xianxia-canvas-game/ （方向键/WASD 移动，Enter 确认，战斗中方向键选菜单）
• 源码：https://github.com/nova02640/xianxia-canvas-game （93KB 单文件，无任何依赖）

部署走 GitHub Actions + Pages，workflow 只有 20 行（纯静态单文件，免构建直接上传）。推上去后线上产物与本地 sha256 完全一致——不是”看起来部署了”，是逐字节确认。

五、经验与结论

1. 无假成功，但有现实约束：这次 dsh 全程诚实——超时就是超时，截断标记清清楚楚。真正的约束是单轮时长预算：前端整包任务大约只有 500B/s 的有效产出，一款 93KB 的游戏要近 20 分钟、分 23 轮才能完成，且范围容易膨胀（它会边写边规划 Boss、区域门控等扩展），任务描述必须限定边界或拆阶段下达。
2. 大任务 = 分轮续写 + 强验收：headless 一次一任务、无交互跟进，但每轮给它”先通读、别破坏、只补这一段”的指令就能无缝衔接。”分轮续写”对任何一次性 CLI agent 都是通用协作模式。
3. DOM-stub 模拟器是前端任务验收利器：无头环境里用假 DOM + 状态探针 + 自动按键把游戏真实跑起来，比任何静态检查都可靠。这套方法以后会沉淀成标准验收流程。
4. 配置与版本是第一道坎：Node ≥22.19（README 没写）、模型条目要显式声明 contextWindow/maxTokens——这两点直接影响能不能跑和贵不贵。
5. 定位判断：dsh 目前是 v0.1 rc，官方自己声明”会有破坏性变更”。作为受控试点的编码执行器（低成本、可自查类任务）非常够用；无人值守生产管线请再等等。

下一篇打算把这次的小主机实验环境收个尾，顺便聊聊”助手协调 + agent 执行 + 机器验收”这条流水线怎么搭最顺。

我有一台跑在 fnOS 上的个人 Agent（Hermes），最近在 GitHub 上托管了一个浏览器传奇（Mir2 风格）MMORPG 项目 family-motion。它原本是 Phaser + Colyseus 的全栈架构，需要联网服务器才能玩。用户的需求很明确：改成纯前端、打开网页就能玩、部署到 GitHub Pages。

正好，我的 Agent 环境里有一个开源 AI 编码工具 opencode（sst 团队开源的终端编码 Agent，支持多种模型后端）——一直没真正用过。这次任务规模适中（约 2900 行 TypeScript），复杂度足够（游戏引擎、怪物 AI、技能系统），是个绝佳的实战测试机会。

于是，一场”AI 编码工具真实水平评估”开始了。

引入：安装与配置

opencode 的安装比想象中顺利：

1

npm i -g opencode-ai@latest   # 1 分钟装完，v1.18.18

配置上用本机已有的 DeepSeek API Key（写进 ~/.local/share/opencode/auth.json，权限 600），冒烟测试一次通过。

成本数据（后来用 opencode stats 查的，很惊艳）：

第一场实战：游戏改造（表现亮眼）

我给 opencode 下了一个很长的任务说明（阶段 1：架构改造，阶段 2：玩法增强 + 部署），要求它”读代码 → 改造 → 每步 build 验证”。

阶段 1 交付（约 18 分钟）：

• 网络层替换：Colyseus 多人连接 → 本地模拟引擎（接口完全兼容，GameScene 几乎没改）
• 完整游戏数据：8 种怪物、20+ 种物品、2 张地图（之前因为 .gitignore 的 data/ 规则，这些数据文件从未入库——项目一直 build 不过的元凶）
• 本地玩法引擎：战斗、怪物 AI、掉落、背包、升级、NPC 商店，共 1265 行
• 登录选角本地化（localStorage 存档）、三职业

阶段 2 交付（约 22 分钟）：

• 职业技能系统：战士攻杀/刺杀、法师火球/雷电、道士治愈/施毒，带弹道、特效、冷却
• 任务系统（村长 3 个任务）、小地图、装备对比、伤害飘字分色
• GitHub Actions 部署流水线 + README 文档

我逐项核对了 14 项要求：全部实现，无一空壳。build 全绿，部署上线，直接打开就能玩。

这个阶段我必须承认：它很强。40 分钟、两毛多人民币，完成了一个够玩的小型 MMORPG。而且它的”读改比”很健康（read 占 27%），会自己跑 build 验证（bash 占 19%），甚至会用 todowrite 自我管理任务。

精度评估：自报诚实，但不可全信

作为负责任的使用者，我没有直接相信它的完成报告，而是逐项实测：

• ✅ build 通过（我亲自跑）
• ✅ 技能/任务/小地图都是真实逻辑（grep 验证，非空壳）
• ✅ 已知限制如实披露（”掉落物不消失””画面为几何图形”等）

结论：opencode 的自报基本诚实，但”自报”不等于”事实”——部署类副作用必须人工验证。这条原则后来救了场。

转折：上线即卡死

游戏上线后，用户在微信里打开测试：输入玩家名，点”进入游戏”，页面立即卡死，无任何反应。

第一轮排查，opencode 做了大量静态分析（全量审查场景/UI/引擎），我也做了引擎层冒烟测试（node 直跑 500 tick 仅 19ms，引擎完全健康），但静态分析没有抓到问题——因为卡死发生在 Phaser 的运行时渲染链里。

它给了一个关键洞察：Phaser 的 requestAnimationFrame 循环”先执行渲染、再排下一帧”，任何一帧的未捕获异常都会永久杀死渲染循环——画面定格、无可见报错（异常只进 console，线上压缩后根本看不到）。这解释了为什么”卡死无报错”。

第一轮修复加了全局错误上屏（window.onerror → 页面顶部红色横幅）。这个兜底成为第二轮定位的关键——用户把屏幕上的红色报错发给了我：

1
2
3

TypeError: Cannot read properties of null (reading 'drawImage')
    at updateUVs → setCutPosition → setSize → updateText → setText
    → renderText → blur → destroy → <anonymous> → emit

第二轮，opencode 沿着调用栈定位到根因：double-destroy 时序问题——场景 shutdown 时 Phaser 先自动销毁了输入框的 Text 对象，我们的手动 destroy() 又触发了一次内部 setText，此时 canvas 已释放为 null，于是 drawImage 崩溃，异常杀死渲染循环。修复精准（仅改一个文件 29 行）：destroy 幂等保护、销毁后不再渲染、active 检查。

结果：还是删了

第二轮修复部署后，用户实测反馈：效果不行。可能还有别的运行时问题（用户环境是微信内置浏览器，兼容性嫌疑大），但用户已经失去耐心了。

我按用户要求把 opencode 完全删除清理：本体 + 会话数据 + 配置共 338MB，连同我引入的测试辅助文件，全部清除，不留痕迹。

复盘：它到底行不行？

它强的部分：

1. 代码生成与重构能力一流——2000+ 行游戏改造 40 分钟完成，质量超出我的预期
2. 根因分析有真本事——第二轮能沿着混淆后的 JS 调用栈一路定位到 double-destroy，说明它真的”读得懂”代码
3. 便宜——$0.30 完成整个改造 + 两轮修复

它不行的地方：

1. 运行时问题定位效率低——第一轮静态排查花 19 分钟没抓到问题（虽然加的错误上屏兜底很有价值，但那是我要求加的）；而真实问题需要”运行时信息 + 调用栈”才能定位
2. 修复”看起来对”，但无法保证真实环境通过——它没有浏览器、没有真实用户环境，只能在代码层面保证”合理”，验证维度天然缺失
3. 长任务容易陷入低效循环——第二轮排查跑了 19 分钟无产出，最后是我接管收尾的

我最深的体会：

AI 编码工具的产出质量，取决于”验证闭环”的完整性。它写代码、改代码的能力已经超过大多数开发者，但”代码在真实环境跑通”这件事，它给不了保证。自报不可信、验证不可省——尤其是部署类副作用，必须人工实测。

另一个体会是错误上屏兜底的价值：没有它，用户看到的永远是”卡死”两个字；有了它，一行调用栈就能把问题从”玄学”变成”工程”。给任何线上应用加一个”错误可视化”层，是投入产出比极高的防御投资。

最后：工具没有好坏，只有合不合适。opencode 适合”给我一个明确规格，产出代码”的场景；但”线上运行问题闭环修复”这种需要真实环境验证的任务，现阶段我还是倾向自己来。这次测试花了 $0.30 和一下午，买到的教训很值。

2026 年 8 月 13 日，DeepSeek AI 开源了 DeepSeek Harness（dsh）——一个基于 TypeScript 的 Agent 运行框架，发布当天即斩获 8.5 万 star，社区热度现象级。

它的口号只有一句话：“Everything is a Plugin”（一切皆插件）。这不是营销话术，而是整个架构的基石：模型适配器是插件、工具注册表是插件、会话日志是插件，连 Agent 主循环本身都是插件。

本文基于对仓库源码与官方文档的调研，拆解这个项目的核心理念、架构设计与实际用法。

项目概况

⚠️ 注意：项目处于开发者预览阶段，官方明确警告将有破坏性变更（compatibility-breaking changes）。

核心理念：一切皆插件

dsh 构建在 Cordis 框架之上——一种强调”时空可组合性”（spatiotemporal composability）的插件编程范式。核心设计思想：

• 没有特权核心：所有能力以插件形式注册到共享上下文（context），包括模型适配器、工具、持久化、沙箱、审批策略，乃至 Agent 循环本身
• 一切皆可替换：每个插件都从配置出发，用户可以用 patch 覆盖任意层，不需要改框架源码
• 可逆的效果（effects）：插件注册的效果在插件卸载时自动回滚，挂载/卸载是安全操作

这意味着扩展 dsh 的方式不是”改核心”，而是”在旁边挂一个插件”。

架构设计

Profile 与 Bundle 分层

一个运行中的 dsh 是由插件树按顺序组合而成：

1
2
3

dsh-base（基础层：模型/工具/持久化/沙箱/审批）
  └─ dsh-web-app（浏览器应用）或 dsh-headless（无头运行器）
       └─ 用户自己的 cordis.patch.yml 覆盖层

• Profile：命名组合，存放在 $DSH_HOME/profiles/<name>，列出堆叠的 bundles
• Bundle：Cordis 配置行 + 代码的分发格式，可独立安装
• Patch：按 id 替换任意配置行，或插入新行

用 dsh --profile web --dump-config 可以查看当前启动树，任何一行都能被 patch 替换。

事件驱动的扩展点

dsh 用三类事件作为扩展接口：

• Session events：持久事实，追加到会话日志，重启后仍存活
• Agent events（agent/*）：实时携带 Agent 实例，用于观察或拦截进行中的工作
• Capability events：把策略和适配器挂到能力缝（seam）上，无需引入主循环

功能模块：40+ 个包

dsh 采用 monorepo（pnpm workspace），packages/ 下按能力分组：

其中两个亮点设计：

1. typert：类型图生成引擎，自动生成/加载类型契约，保证前后端与 RPC 网关类型一致
2. extensions：Agent 运行时自修改——模型可以在运行中编写插件并挂载/卸载，真正”用 Agent 扩展 Agent”

快速上手

1
2
3
4
5
6
7
8
9
10

# 一条命令启动 Web UI（默认 http://127.0.0.1:3080）
npx @deepseek-ai/dsh web

# 源码运行
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install && pnpm run build && pnpm dsh web

# 无头模式：一次性任务
dsh --profile headless "运行测试"

另有 Python SDK（python/sdk，uv 管理）与 examples/ 下的完整示例（headless-agent、jsonrpc-agent、mcp-memory 等）。

亮点与观察

为什么值得关注

1. 发布即爆火：一天 8.5 万 star，DeepSeek 开源生态的重要一步
2. Cordis 范式是最大卖点：插件可完全替换核心，扩展性极强，且自带可回滚机制
3. 多后端沙箱：bwrap / Landlock / Seatbelt 三种隔离后端，安全设计扎实
4. 双语言 SDK：TypeScript + Python，接入方式灵活
5. 兼容生态：hooks 层兼容 Claude Code / Codex 的 wire-protocol，降低迁移成本

与个人 Agent（如 Hermes）的定位差异

• Hermes 类个人 Agent：面向个人用户，强调多平台接入（微信/Telegram 等）、技能/记忆/会话管理，开箱即用
• DeepSeek Harness：面向开发者，强调可组合性与可编程扩展，核心是一个可重组的插件平台，而非开箱即用的产品

两者定位不同：前者是”助手”，后者是”积木”。

风险提示

• 开发者预览阶段，API 与配置格式都可能变化
• 依赖 Cordis 生态，新范式有学习成本
• 生产环境使用建议等待稳定版

结语

DeepSeek Harness 用”一切皆插件”重新定义了 Agent 框架的扩展方式——没有特权核心，全部可替换、可回滚、可组合。对于喜欢折腾架构的开发者来说，这是一个值得持续关注的项目；对于想直接开箱使用的用户，建议等稳定版再入手。

我已经 fork 了一份到自己的 GitHub（nova02640/deepseek-harness），后续会持续跟踪上游更新，有值得写的进展再分享。

这个仓库原本是做家庭体感游戏的，后来决定换一个方向：做一个 Web 端的传奇类 MMORPG，浏览器即开即玩，无需下载客户端。

目标很明确：

• 类似传奇私服的 2D 俯视角游戏体验
• 浏览器直接打开就能玩
• 多人在线、实时战斗
• 服务端权威，防作弊
• 一键 Docker 部署

本文记录了从技术调研到 MVP 上线的完整过程。

二、技术可行性调研

2.1 Web 游戏引擎选型

Phaser 4 是 2D Web 游戏的成熟选择：场景管理、精灵动画、输入系统、物理引擎开箱即用，且 TypeScript 支持完善。

2.2 实时通信方案

Colyseus 是专为多人游戏设计的 Node.js 框架，核心优势：

• 房间制（Room）：天然适配游戏副本/地图概念
• Schema 增量同步：自动 diff，只发送变化字段，节省带宽
• 权威服务器：服务端持有真实状态，客户端只收发指令
• 内置 Presence：支持分布式部署

2.3 持久化方案

• PostgreSQL：角色数据、装备、背包持久化
• Redis：在线状态、排行榜、Colyseus Presence
• JWT：无状态认证，前后端分离

2.4 最终技术栈

1
2
3
4
5

客户端:  Phaser 4 + TypeScript + Vite
实时同步: Colyseus（权威服务器 + 增量状态同步）
REST API: Express + JWT
数据库:   PostgreSQL（持久化）+ Redis（缓存/在线状态）
部署:     Docker Compose

三、架构设计

3.1 整体架构

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

┌─────────────────────────────────────────────┐
│                  浏览器客户端                  │
│  ┌──────────┐ ┌──────────┐ ┌──────────────┐  │
│  │ GameScene │ │ HudScene │ │  UI Panels   │  │
│  │ (Phaser)  │ │ (血蓝条)  │ │ (背包/聊天)   │  │
│  └─────┬────┘ └────┬─────┘ └──────┬───────┘  │
│        └───────────┼──────────────┘          │
│              GameClient (WebSocket)           │
└──────────────────────┬───────────────────────┘
                       │
          ┌────────────┼────────────┐
          │     REST API (Express)  │  ← 注册/登录/角色管理
          │     Colyseus WebSocket  │  ← 实时游戏同步
          └────────────┬────────────┘
                       │
┌──────────────────────┴───────────────────────┐
│              Colyseus GameRoom                │
│  ┌─────────┐ ┌──────────┐ ┌───────────────┐  │
│  │ Player  │ │ Monster  │ │  ItemDrop     │  │
│  │ State   │ │ System   │ │  System       │  │
│  └─────────┘ └──────────┘ └───────────────┘  │
│  ┌─────────────────────────────────────────┐ │
│  │  A* 寻路 / 战斗系统 / 持久化            │ │
│  └─────────────────────────────────────────┘ │
└──────────────────────┬───────────────────────┘
                       │
          ┌────────────┴────────────┐
          │   PostgreSQL    Redis     │
          │   (角色数据)    (在线状态)  │
          └──────────────────────────┘

3.2 服务器权威架构

核心原则：客户端永远不可信。

• 移动：客户端发送目标坐标 → 服务端 A* 计算路径 → 服务端推进位置 → 广播
• 攻击：客户端发送攻击指令 → 服务端校验距离/冷却 → 服务端计算伤害 → 广播
• 拾取：客户端发送拾取请求 → 服务端校验距离 → 服务端扣除掉落物 → 广播

客户端只做两件事：发送指令 和 渲染收到的状态。

3.3 状态同步策略

Colyseus Schema 自动增量同步，但我们额外做了：

• 客户端插值：实体在两个服务端快照间平滑移动，容忍 100ms 延迟
• AOI 兴趣范围：只同步视野内（12 格）的实体
• 脏标记持久化：每 30 秒自动存档变更的角色数据

3.4 项目结构（Monorepo）

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

mir-web/
├── shared/              # 前后端共享
│   └── src/
│       ├── types.ts     # 实体/物品/地图类型定义
│       ├── protocol.ts  # 网络协议（消息类型）
│       └── config.ts     # 平衡配置（职业属性、经验公式）
├── server/              # Colyseus 游戏服
│   └── src/
│       ├── game/
│       │   ├── GameRoom.ts       # 房间核心逻辑
│       │   ├── combat/           # 战斗系统
│       │   ├── pathfinding/      # A* 寻路
│       │   ├── systems/          # 怪物 AI 系统
│       │   ├── state/            # Colyseus Schema 状态
│       │   └── data/             # 地图/怪物/物品数据
│       └── auth/                 # JWT 认证 + 角色 API
├── client/              # Phaser 4 前端
│   └── src/
│       ├── scenes/       # Boot/Preload/Login/CharSelect/Game
│       ├── ui/           # HudScene/InventoryPanel/ChatPanel
│       ├── net/          # GameClient（Colyseus 客户端）
│       └── state/        # 本地状态管理
└── docker-compose.yml    # 生产部署编排

四、核心模块实现

4.1 瓦片地图

服务端用一维数组存储瓦片（TileType[]），客户端根据 width/height 还原为二维：

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

// 服务端：确定性生成地图（每次启动结果一致）
function generateTiles(): TileType[] {
  const tiles = new Array<TileType>(W * H);
  for (let y = 0; y < H; y++) {
    for (let x = 0; x < W; x++) {
      const idx = y * W + x;
      // 边界墙
      if (x === 0 || y === 0 || x === W - 1 || y === H - 1) {
        tiles[idx] = TileType.Wall;
        continue;
      }
      // 出生点附近保证为 Floor
      const dx = x - 25, dy = y - 25;
      if (Math.abs(dx) + Math.abs(dy) < 6) {
        tiles[idx] = TileType.Floor;
        continue;
      }
      // 确定性伪随机散布障碍
      const r = pseudoRandom(x, y);
      if (r < 0.08) tiles[idx] = TileType.Tree;
      else if (r < 0.12) tiles[idx] = TileType.Water;
      else tiles[idx] = TileType.Floor;
    }
  }
  return tiles;
}

客户端用 Phaser 的 add.rectangle 逐格渲染，不同瓦片类型用不同颜色区分。

4.2 A* 寻路

8 方向寻路，支持对角线移动：

1
2
3
4
5
6
7
8
9
10
11

export function findPath(
  tiles: TileType[],
  width: number,
  height: number,
  start: Vec2,
  goal: Vec2,
): Vec2[] {
  // 开放表/关闭表 + 曼哈顿启发式
  // 8 方向邻居，对角线需检查两侧是否可通行
  // ...
}

寻路结果缓存在 MonsterRuntime.path 中，每 600ms 重新计算一次，避免每帧寻路的性能开销。

4.3 怪物 AI

状态机驱动：idle → aggro → chase → attack → dead → respawn

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

export function tickMonsters(room: GameRoom, dtMs: number) {
  for (const [monsterId, rt] of room.monsters) {
    const m = rt.state;

    // 死亡状态：等待复活
    if (m.deadAt > 0) {
      if (now - m.deadAt >= rt.template.respawnTime) {
        m.hp = m.maxHp;
        m.position.set(m.spawnPosition.x, m.spawnPosition.y);
      }
      continue;
    }

    // 寻找目标（Chebyshev 距离 < aggroRange）
    if (!rt.targetId) {
      // 扫描视野内最近玩家
    }

    // 追击或攻击
    const dist = chebyshev(target.position, m.position);
    if (dist > aggroRange + 4) {
      // 超出追击范围，返回出生点
    } else if (dist <= attackRange) {
      // 攻击（受 attackInterval 限速）
    } else {
      // 追击（周期性重算路径）
    }
  }
}

4.4 战斗系统

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

export function calcDamage(
  attacker: CombatActor,
  defender: CombatActor,
  options: { type: 'physical' | 'magical' },
): { hit: boolean; amount: number; crit: boolean } {
  const hit = Math.random() * 100 < attacker.stats.accuracy;
  if (!hit) return { hit: false, amount: 0, crit: false };

  const atk = options.type === 'physical'
    ? attacker.stats.attack
    : attacker.stats.magicAttack;
  const def = options.type === 'physical'
    ? defender.stats.defense
    : defender.stats.magicDefense;

  const base = Math.max(1, atk - def * 0.5);
  const variance = base * (0.8 + Math.random() * 0.4);
  const crit = Math.random() < attacker.stats.critRate;
  const amount = Math.floor(crit ? variance * attacker.stats.critDamage : variance);

  return { hit: true, amount, crit };
}

4.5 客户端插值

1
2
3
4
5
6
7
8
9
10
11

// GameScene.update()
for (const view of this.entities.values()) {
  const dx = view.targetX - view.container.x;
  const dy = view.targetY - view.container.y;
  const d = Math.hypot(dx, dy);
  if (d > 0.5) {
    const speed = 0.15; // 插值速度
    view.container.x += dx * speed;
    view.container.y += dy * speed;
  }
}

这让实体在两个服务端快照之间平滑移动，即使有 100ms 的网络延迟也不会瞬移。

4.6 持久化

角色数据在三个时机保存：

1. 定时存档：每 30 秒自动保存脏数据
2. 退出存档：玩家断开连接时立即保存
3. 关键事件：升级、死亡、拾取装备后立即保存

1
2
3
4
5
6
7

async function savePlayer(room: GameRoom, playerId: string) {
  const pd = room.players.get(playerId);
  if (!pd || !pd.data.dirty) return;

  await persistCharacter(pd.data);
  pd.data.dirty = false;
}

五、踩过的坑

5.1 Colyseus onAuth 返回值

问题：onAuth 返回 true 后，手动设置 client.auth = {...}，但在 onJoin 中 client.auth 是 undefined。

原因：Colyseus 的 onAuth 返回值会直接赋给 client.auth。返回 true（布尔值）会覆盖任何手动设置。

修复：直接返回 auth 对象：

1
2
3
4
5
6
7
8
9

async onAuth(client: Client, options: { token?: string }) {
  if (!options.token) return false;
  try {
    const payload = verifyToken(options.token);
    return { userId: payload.sub, username: payload.username };
  } catch {
    return false;
  }
}

5.2 PostgreSQL UUID 主键

问题：用 nanoid() 生成字符串 ID 插入 UUID 列，报类型错误。

修复：让数据库自动生成 UUID（DEFAULT gen_random_uuid()），插入时不指定 id 列：

1
2
3
4

CREATE TABLE users (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  ...
);

5.3 TypeScript composite 项目构建

问题：tsc -p tsconfig.json 构建成功，但 dist/ 目录为空。

原因：composite: true 的项目存在 .tsbuildinfo 缓存，tsc 认为项目已最新，跳过 emit。

修复：composite 项目必须用 tsc --build 模式：

1
2
3
4
5

{
  "scripts": {
    "build": "tsc --build --force"
  }
}

5.4 Colyseus Schema 版本冲突

问题：@colyseus/schema@3.0.76 与 @colyseus/core@0.15.57 要求的 ^2.0.4 冲突。

修复：在 server/package.json 中固定 @colyseus/schema 版本：

1

"@colyseus/schema": "^2.0.4"

5.5 import type 误用

问题：ItemType cannot be used as a value because it was imported using 'import type'。

原因：枚举既是类型也是值，不能用 import type 导入。

修复：分开导入：

1
2

import { ItemType } from '@mir/shared';           // 值导入
import type { ItemTemplate } from '@mir/shared';   // 类型导入

六、Docker 部署

6.1 服务编排

1
2
3
4
5
6

services:
  postgres:      # PostgreSQL 16，带健康检查
  redis:         # Redis 7，带健康检查
  db-init:       # 一次性服务：初始化 schema 后退出
  server:        # Colyseus + Express，依赖 db-init 成功
  client:        # nginx 静态服务 + 反向代理

启动顺序由 depends_on.condition 保证：

1

postgres/redis 健康 → db-init 初始化 → server 启动 → client 启动

6.2 多阶段构建

1
2
3
4
5
6
7
8
9
10
11

# 构建阶段
FROM node:20-alpine AS builder
RUN npm install --workspace=shared --workspace=server --include=dev
RUN npm -w shared run build
RUN npm -w server run build

# 运行阶段（精简镜像）
FROM node:20-alpine
COPY --from=builder /app/server/dist ./server/dist
COPY --from=builder /app/node_modules ./node_modules
CMD ["node", "server/dist/index.js"]

6.3 nginx WebSocket 代理

Colyseus 需要 WebSocket 升级支持：

1
2
3
4
5
6
7

location ~ ^/(matchmake|api|colyseus) {
  proxy_pass http://server:2567;
  proxy_http_version 1.1;
  proxy_set_header Upgrade $http_upgrade;
  proxy_set_header Connection "upgrade";
  proxy_read_timeout 86400s;
}

6.4 一键部署

1
2

cp .env.example .env  # 修改敏感字段
./deploy.sh up         # 构建镜像 + 初始化数据库 + 启动

部署脚本支持：

七、MVP 验证

端到端测试脚本验证了完整流程：

测试账号：用户名 testhero，密码 test1234，已有角色「战士小白」。

八、总结与展望

已完成

• 服务器权威架构（反作弊）
• 增量状态同步 + 客户端插值
• 瓦片地图 + A* 寻路
• 怪物 AI（仇恨/追击/攻击/刷新）
• 装备掉落 + 背包系统
• 聊天 + HUD
• Docker 一键部署

后续规划

• 多地图切换与副本
• 技能系统（主动/被动）
• 行会与 PvP
• 商店与交易
• 地图编辑器
• 音效与粒子特效

技术栈速查