AI 是放大器：你自己越清楚”要什么、边界在哪、怎么验证”，它越好用；反过来，你越模糊，它就把你的模糊放大成更大的乱子。这篇讲三条原则，帮你既用上 AI、又不失控。
把”接口契约”攥在自己手里，把”内部实现”扔给 AI。
这样做的好处是：即使 AI 在内部改得乱七八糟，只要边界不变，它波及不到外部。出问题你也知道问题在”内部实现”这一块，而不是”整条链路都塌了”。
反过来，如果你连边界都放任 AI 定，它一改，可能把”只有一个入口”“必须幂等”这种你默认为真的约定给打破——那才是最要命的。
这是最容易被忽略、也最容易出事的。
AI 帮你在每个小步里做验证（编译、跑测试、看结果），你就能随时确认”这步没问题”。小步，是可控的前提。
这是底线。AI 改的代码，你得能看懂，得能一键回滚。
“看不到改动”是最危险的状态——你不知道它碰了哪里，自然就不知道该怎么救。
有些东西，别让 AI 随便碰：
AI 是生产力，但它不会为你负责。你越早把”边界、验证、回滚”这三点立起来，它就越是从”帮你走捷径”变成”帮你干活”，而不是”替你做决定”。
让 AI 干活可以，但方向盘和刹车，得一直握在自己手里。
]]>先纠正一个心态：你不需要”看懂”黑盒，你需要的是摸清它的”边界”。黑盒系统本质上就是”给定某类输入，能吐出某类输出”。你只要知道：
把这些摸清楚，你就能用起来了，哪怕内部你一无所知。这比硬读它的内部要快得多。
别一上来就想着”我得搞懂它的完整功能”。先做最小试探：给一个最简单的输入，看它返回什么；换一个字段，看返回值怎么变。几次下来，它的”输入输出契约”就浮出来了。
这一步的关键是让变化可控：一次只改一个变量，观察结果。这样你才能把”哪个输入影响了哪个输出”对应上，而不是被一堆变化搞晕。
如果它是个 jar、zip、或者编译产物，别等文档，直接看它自己暴露出来的东西：
这一步的收益极大：你以为是”没人知道的东西”，其实大多就藏在它自己的产物里。
黑盒系统往往能”用多种方式跑”，但真正稳的只有一种。比如你手里有个 Java 的包，那就老老实实用 Java 跑，别拿 Python 去启动它——语言和运行环境不匹配，只会引入一堆无关的坑。
我的做法是：先找到那一个能跑通的最小链路，把它跑起来，再在这个基础上加东西。 一开始就追求花哨的启动/集成方式，很容易把”环境不匹配”的错，当成”系统做不了”的错觉。
黑盒除了输入输出，还有一类用文档看不出来、只能试出来的特性：
这些特性决定你能不能”插队”、能不能热更新。越早摸清这些，越少在后面被它卡住。
跟黑盒打交道，靠的不是了解，是观察、试探、记录。把这三招用熟，你会发现”没文档”其实没那么可怕。
]]>我在做多端 IM 接入（dsh-im）时，9 个渠道在这里花的功夫，比想象中多得多。这篇讲验签差异为什么会成为隐性成本。
webhook 是渠道把事件推给你的公开入口。任何能访问到这个 URL 的人，都能伪装给系统”喂消息”。如果没有可靠的验签，就等于任何人都能冒充渠道给你的机器人发指令。
所以 webhook 处理的第一件事不是”解析消息”，而是先验签，确认这条消息真的是渠道发的。验签不过，直接拒收，别往下走。
麻烦就麻烦在，“验签”没有统一标准，每个渠道一套：
timestamp 防重放，有的不会；同一套代码，换个渠道就要重新写一遍验签，还不能复用。
好消息是，验签虽然每渠道不同，但它和”消息格式转换”是同一类问题——渠道差异，收敛到适配器里。
所以我把验签也放进每个渠道的适配器：适配器内部实现”这个渠道怎么验”，对外暴露一个统一的接口，比如 bool verify(event, headers, body)。上层只调用这个，不用知道底下是谁、用什么算法。
这样做的安全价值很直接：
验签看起来是小事，但它决定了你的入口是开着还是关着。把这个隐性成本认清，是接入多渠道很重要的一步。
]]>一个定时任务插件，到点本该正常触发一个 Agent 会话，却在任务名改成中文之后，整条链路报出一个让人摸不着头脑的错误：TRANSPORT。单看这个字段，大家第一反应都是“网络传输断了”，于是去查代理、查超时、查对端是否在线，查了半天一无所获——因为问题从头到尾就不是网络。
这篇文章记录我修复的一个真实故障：中文任务名是如何一路变成跨平台请求里的字节问题、最终被系统标成 TRANSPORT 的。细节以实际项目为准，但它揭示的“编码链路”问题在跨平台、跨字节编码的对接里非常典型。
故障表现为：创建定时任务时，任务标题是中文；到点触发时，宿主要求用“真实 Agent 会话”去执行 prompt。结果这些中文任务名被一路带进了会话标识里，在把请求发到模型服务时，被系统在请求层拦下，抛出一个被归类为 TRANSPORT 的错误。
TRANSPORT 这个名字有极强的误导性——它让人以为问题出在“传输层”。但翻到真正抛错的地方，是对端在解析请求头时，遇到了一个非 ASCII 的字节序列，它按字节串（ByteString）去解析时失败了。换句话说：传输层根本没出问题，是请求里带了一个它无法接受的字节串。
那个非 ASCII 的东西，就是中文任务名被写进会话 ID 之后留下的痕迹。
定位时我把 TRANSPORT 这个错误名先放一边，去翻了真正抛错的那一层日志，看到的是“请求头里有一个无法按字节串解析的值”。顺着这个值往上追，发现它来自会话 ID，而会话 ID 来自任务标题。整条链路就清楚了：标题（中文）→ 会话 ID（带中文）→ 请求头（字节串解析失败）→ 报成 TRANSPORT。 问题在“编码链路”，不在“传输链路”。
问题的源头很隐蔽：实现里，任务有一个“标题”（给人看的中文），会话又有一个内部 session id。最省事的写法，是让两者共用同一个字段——标题是什么，session id 就是什么。这样界面好看、逻辑也简单。
但内部 ID 的用途和标题完全不同：它要进 URL、进请求头、进各种需要严格 ASCII 的协议边界。一旦塞进中文，就突破了这些边界对字节的限制。中文在 UTF-8 里是多字节的，请求头按 ASCII/ByteString 解析时就会炸。
所以根因不是“网络”，而是把一个展示字段错误地复用了成协议字段。展示名允许任意字符，内部标识必须被严格约束。
正确的修法不是“以后别用中文”——那只是绕过，不是修复。这也是我在主页里写“没有停在‘改成英文绕过去’”的原因。绕过去，等哪天用户用了个别的特殊字符，故障会原样回来。
我的做法是：会话 ID 只允许 ASCII。 中文不再写入 session id，而是单独作为展示标题存在；内部标识由一套只含 ASCII 的规则生成，保证它无论进 URL、进请求头还是进其他协议边界都安全。
这一步的实质是：分清“给人看的字段”和“给机器用的字段”，让它们各自遵守自己的字符集约束，而不是共用同一个值去省事。展示层可以随便花哨，协议层必须保守。
光改代码不够，得把这条规则写进测试，防止以后谁又“顺手”把标题写回 ID。
这个项目有一条行为级 E2E，用的是假 host，无需完整的 DSH 运行时也能跑。覆盖项里就专门有一条：“中文标题 → ASCII session id”。也就是说，创建一个中文标题的任务，断言生成出来的内部会话 ID 是纯 ASCII，而不是中文原文。
这比口头约定可靠得多：只要有人把规则改回去，测试立刻变红，也就能在发布前拦住，而不是等用户踩到才报障。
修复还有一个绕不开的点：已经生成的旧会话，其 ID 里可能已经带了非 ASCII。 打开它们时，仍可能触发 TRANSPORT。如果没有兼容策略，用户会遇到“明明更新了，老任务还是坏”的困惑。
处理方式是：不强行改历史数据（改了会破坏会话绑定），而是在文档里明确说明——旧会话如果 ID 含非 ASCII，请用新版本重新「立即执行」生成新会话；同时把这条作为一个已知限制写清楚。这样用户拿到的是一个“知道该怎么处理”的版本，而不是一个“看起来修了其实暗坑还在”的版本。
TRANSPORT 这类错误名会骗人：先看抛错位置的字节约束，别急着查网络。一次跨平台故障，最后落在“字节字符串”上，而不是“网络”上——这本身就是个提醒：报错信息说“哪里出了问题”，未必是“真正出问题的地方”。顺着编码链路去看，比对着错误名去猜，要快得多。
]]>我在做一个 DSH 定时任务插件（dsh-timer-agent），它就是在宿主进程内做 cron 调度，到点驱动真实的 Agent 会话。这篇讲讲这个取舍。
独立调度器看起来美好，实际会带来一堆和核心无关的复杂度：
如果你的定时任务就是要驱动同一个运行时里的 Agent 会话，那把这层通信拆到进程外，是把简单的事做复杂了。
在宿主进程里做 cron，最直接的好处是上下文共享：定时器到点，直接能拿到来驱动会话所需的一切——运行时、配置、会话对象。不需要序列化、不需要网络调用、不需要额外部署。代码更短，也更不容易坏。
而且它天然贴近真实场景：你调度的是这个运行时的 Agent，那就该在它身边调度，而不是隔着进程猜。
有人会问：宿主进程一崩，定时任务不就没了吗？对。这正是”宿主内 vs 独立”的核心权衡，也是你必须想清楚的点。
我的取舍是：接受”宿主进程存续期间“这个前置条件——定时任务的生命周期跟随宿主进程。够用，因为要驱动的是宿主内的会话；进程不在，会话本来也没了。
所以重点不是”怎么让它跨进程存活”，而是怎么让丢失可被感知。这里有个很实在的原则：“丢一次”和”重跑一遍”，要选一个并明确说明。
不声明、不观测的”丢了就丢”，是最危险的。
这个项目里有个挺典型的问题：中文任务名被错误地带进了跨平台的会话标识，导致请求头序列化失败、被误判成 TRANSPORT 错误。绕过去？不，要修根因——把展示名和用 ASCII 标识的会话 ID 解耦，并补回归测试（”中文标题 → ASCII session id”）。
这类问题很能说明”宿主内调度”的一个特质：它是和运行时长在一起的，所以运行时里任何一点脏数据，都可能被定时器放大成故障。定时器虽然是”宿主内”的，但它的健壮性和运行时是绑定的。
架构取舍没有标准答案，但你得知道自己选了哪条路、放弃了什么、以及怎么兜底。把这几句话说清楚，比”哪个方案更高大上”重要得多。
]]>这类项目的头号约束是环境。甲方一句话：系统要跑在麒麟操作系统 + ARM 架构上；整个开发是无网络的，你不能开机就去 npm install、去拉公网包、去查文档；调用的 AI 也不是公网 API，而是内部部署的大模型。
这些东西看着是”最后打包的事”，其实在最早就决定了你后面每一步怎么走。所以做这种项目，第一件事不是想功能，是把环境摸清楚：什么系统、什么架构、能不能上网、依赖从哪来、模型从哪来。
无网环境里，”装个包”会变成一件很别扭的事：
npm install / pip install 从公网拉。要么提前把依赖打进内网仓库 / 离线镜像，要么把包一个个拷进来。所以这类项目里，”依赖管理”不是一个流程问题，而是能不能开工的问题。
到了部署环节，架构适配是实打实的活：
这一步最容易被低估：本地能跑 ≠ 目标环境能跑。你不提前在目标环境试一把，最后大概率是”上线才发现跑不起来”。
这类项目往往要求”用内部 AI”，这就引出一个很现实的问题：模型从哪来、算力谁出。
所以”AI 落地”在这个场景下，往往不是”我怎么做一个聪明的 agent”，而是”我怎么把一个别人部署好的模型，可靠地接进我自己的系统“。
无网环境下，你没法在真实环境里连着真实数据跑来跑去，只能靠模拟、靠假数据、靠”先虚拟地跑通”。等真正拿到真实环境，往往才发现一堆没对上的问题。
这跟前面那个”联调时发现字段对不上、只能靠随机数填”是同一个伤口：你没在真实环境里验证过，就永远不知道它通不通。
“环境约束”不是”部署阶段的一次性工作”，它从头到尾都在约束你。
所以拿到这样一个项目，先把”跑在哪、能不能上网、模型从哪来”这几件事问清楚，再开始写第一行代码。 不然你以为自己做的是功能，其实大半精力会被环境拖在泥里。
]]>我在做一个用来生成、审查、规范化中文技术标书与应标材料的 Skill（bid-response-production）。里面最有用的一条规则不是”多写点”，而是“强承诺一定要补边界”。这篇文章讲讲这个结构怎么定的。
标书是不是越长越好？不是。评审看的是”你这条标书有没有把该说的说清楚”。我把它收敛成五段式，每一段解决一类问题：
每段都有明确目的，评审顺着这个结构能快速抓住重点，而不是在冗长的叙述里找线索。
开头还要有一段“标书专属段”——不是把产品介绍复制过来，而是针对这份标书的 800–1200 字：点题、讲清你对应标需求的思路。这段是”钩子”，决定了评审愿不愿意往下看。
没有结构的标书，容易变成”功能清单 + 套话”。而一旦有结构，就逼着你在每个位置写对内容：功能段写实现，技术段写路线，差异段写亮点，验收段写口径。
默认的排版也服务于这个目的：正文宋体、小四、1.5 倍行距，目录清晰、章节分明。一页页翻过去，评审能很快定位到”他要的答案在哪一段”。
这是我最想强调的一点。写标书的人容易犯的毛病是把话说满：
“我们承诺 100% 保证系统 7×24 小时稳定运行，并提供无条件售后。”
这种话看着有诚意，实则是踩雷。因为它是一个没有边界的承诺——真实世界里没有”100% 无条件”的东西，评审一旦追问细节，这句漂亮话就成软肋。
正确的做法是：承诺的同时，把边界一起说清楚：
“我们承诺核心服务可用性 ≥ 99.9%，并配套完整的告警与应急切换；对于非归因于本方的第三方故障，按合同约定承担责任。”
一个承诺 + 一个边界，比一个”满话”可信得多。敢说边界，反而显得专业；只会堆满话，显得心虚。
这套处理我直接做成了规则：review_bid_docx.py 会去审查生成出来的标书，凡是出现”无条件、100%、完全保证、绝对”这类无限承诺的词，就提示你要么加边界、要么改成可度量的指标。生成端 md_to_bid_docx.py 也按这个结构产出，从源头减少”满话”。
把”一定稳定”改成”≥ 99.9%”，把”随时响应”改成”≤ 30 分钟告警、≤ 2 小时响应”，把”无条件支持”改成”明确支持范围与除外情形”。
承诺一旦可度量，评审就没法用”你凭什么说 100%”来攻击你；反而会去讨论”99.9% 的保障机制是什么”，这才是你想被问到的问题。
能经得起追问的标书，才是好标书。而”经得起追问”，靠的不是字数，是每一句承诺都站得住。
]]>1. 代码进去就”死”了 技术分享最重要的料是代码。可代码一进 PPT，就变成了”截图”或”高亮文本”：不能复制、不能点、一页的宽度也塞不下多少行，经常被压缩到看不清。你讲得越细，PPT 越像在”演”，而不是在”讲清楚”。
2. 它是二进制，改不动也看不出来 PPT 文件是二进制，commit 到 git 里，diff 基本是”看不出改了什么”。你改了哪一页、改了哪句话，完全不可追踪。谁改的、改了什么、能不能回滚，全是笔糊涂账。
3. 看的人要先装软件、挑环境 要发给别人看，得想办法导出 PDF、发文件、确认对方能打开。手机上还常常排得乱七八糟。你跟人 say”你打开这个链接就能看”，PPT 做不到。
我博客里现在有一套放映器（演示目录），就是用 HTML/Markdown 写一套可放映的东西。它天然解决上面几个问题：
① 代码是”活”的 代码就是页面里的文本，能复制、能缩放、格式不失真。你还可以直接在页面上做交互，讲起来是”真的给你看代码”，不是”给你看一张代码的图”。
② 它是文本，能进 git 一套幻灯片就是一个 Markdown/HTML 文件，git 能审 diff、能回溯、能回滚。谁改的、改了什么，一目了然。它跟你的代码住在一起，长期维护不成问题。
③ 一个链接就能看 一个 URL，不用装 Office，手机电脑都能看，还能全屏、明暗切换、目录跳页、自动播放。发出去就是”点这个链接”。
我做的这套，常用功能都齐了：
写它的成本也低：一个 layout: slideshow 页面 + 一段段 <section class="slide">，目录还能自动从每页的标题生成。详见教程。
看场景，别跟风。
技术人最常犯的错，是把技术汇报做成了商务 PPT：一堆动画、一张截图代码、讲完什么都没留下。代码该讲的没讲清楚，反而被”包装”稀释了。
PPT 是”给你看”的。HTML 幻灯片是”讲清楚 + 能留下 + 能维护“的。技术分享，我更愿意用后面这个。
下次轮到你讲代码，不妨试试把你那些”方案/复盘/教学”做成一套能放映的 HTML 幻灯片。点开就能讲，讲完还能留在仓库里。
]]>这时候如果你不做处理，就会重复回复、重复建会话、重复触发动作，用户收到两遍消息，或者后台跑了两次同一件事。这篇文章讲我把”去重”落在哪。
别指望渠道”只推一次”。”至少一次”是很多消息系统的默认，你要做的不是祈祷不重，而是让重复变得无害。
所以第一件事是：把”可能重复”当成常态来设计。读回调的代码，默认就是”这可能是我见过的，也可能是新的”。
去重的核心是幂等键——每一条消息/事件，都用一个稳定、唯一的标识来代表”这是我”。常见来源：
message_id、event_id、msgId。这是最可靠的，因为它代表”渠道眼里这一条是什么”；关键是用渠道自己给的 ID，别自己发明。因为渠道重试时，会带着同一个 ID 回来，你才能认出”这条我见过”。
有两种做法：
我更推荐第 2 种：用一个唯一约束兜底，而不是只靠”先查”。单机下可以用内存 set，但要考虑进程重启会丢；有一个持久化、带唯一约束的地方（比如 SQLite 的唯一索引），才真正靠得住。
把幂等做好，你就能坦然面对渠道的每一次重试，而不用提心吊胆。
]]>我在做一个本地优先的企业 Agent 平台（agent-hub），第一版故意做得很小：Python 控制面 + 浏览器界面 + SQLite 存储 + 原生 MCP 面。这一版的目的不是”功能多”，而是把边界和连接方式先验证清楚。这篇讲两个我在意的边界：该不该上多租户，以及 MCP 工具该暴露多细。
第一版默认只绑定 127.0.0.1，没有鉴权，也不是生产多租户服务。听起来是不是”太简陋”？其实这是故意的。
在没有明确多租户需求之前，硬上鉴权、租户隔离、云部署，会带来一堆和核心价值无关的复杂度。而一个本地控制面的核心价值是：让 Agent 能在一个真实、可运行的本地环境里组织工作区、有 MCP 可接入。先把这条链路跑通，比先做隔离重要得多。
所以我用一个显式开关来控制边界：默认拒绝远程绑定，只有显式设置 AGENT_HUB_ALLOW_REMOTE=1 才允许远程。这等于把”要不要对外开放”这个决定，从代码层面逼着你去主动表态，而不是默认就对所有人开放。
MCP 面是给 Agent 运行时接入用的 http://127.0.0.1:8765/mcp。第一版我只放了三个工具：
agenthub_status —— 查整体状态；workspace_list —— 列工作区；workspace_create —— 创建工作区。看着是不是”太少了”？但这是有意控制的。
工具太细，Agent 会被细节淹没：一堆零碎的工具，调用成本高、参数难对齐、Agent 容易选错。工具太少又会不够用，连基本操作都要绕。
判断粒度对不对，我有个朴素标准：这个工具是不是对应一个 Agent 能理解、能直接完成的”业务动作”。
换句话说，工具应该对应”意图”，而不是对应”内部函数”。内部实现怎么拆，是控制面自己的事；对外暴露的，是 Agent 能直接用的动作。
等真实的”多租户 / 远程”需求出现，再往上叠加，而不是提前为想象的需求买单。很多系统是被”万一以后用得上”拖垮的。
AGENT_HUB_ALLOW_REMOTE）决定是否对外。一个”边界清楚、能跑起来”的本地控制面，比一个”什么都想装、却处处没做实”的大平台有用得多。
]]>