2026-09-20 13:00:00
过去一两年，大模型的发展方向几乎都是更长的思考链、更大的上下文、更强的 Agent 能力。但在日常写代码和搭建自动化流程的过程中，我发现很多地方用到大模型，其实只是为了让它做一个简单的判断，却要付出几秒钟的等待和解析 JSON 的麻烦。TypeSafe AI 发布的 Jev 走了一条相反的路：不聊天、不写代码，只做快速的判断。
Jev 是 [[TypeSafe AI]] 在 2026 年 9 月 15 日以抢先体验（early access）形式发布的第一个公开模型，也是官方提出的第一个 System One 模型。Jev 不生成文字，而是做判断：输入一段非结构化的上下文，加上事先定义好的问题和可选答案，Jev 直接返回带概率的结构化结果，代码可以拿来直接做分支、排序或路由。
官方对它的定位是一句话：
Think of Jev as a frontier-intelligence function call: unstructured state in, typed probabilistic decisions out.
也就是说，Jev 更像一个「带智能的函数调用」，而不是聊天机器人。
传统的 LLM 的主要能力是和人聊天，以及在 Coding Agent 上生成代码。但在真实的软件和自动化流程里，很多环节并不需要一段文字，而只需要一个决定：这封邮件是否紧急、这个工单交给哪个部门、这条评论是否违规。用 LLM 来做这些事，通常要写 Prompt、等模型逐字生成、再解析输出，速度慢、成本高，还可能遇到格式错误。Jev 就是为这类场景设计的，官方把它称为「smart if-statements」，即可以嵌进普通代码里的智能判断规则。
官方把 Jev 模型称为 System One 模型，灵感来自 [[Daniel Kahneman]] 的《[[思考，快与慢]]》。
系统一是人类大脑中负责快速直觉判断的部分，系统二是负责缓慢、深度推理的部分。现在的大语言模型通过思维链等方式，越来越往系统二的方向发展；Jev 则反过来，专注于系统一，即「一个知识丰富的人在几秒钟之内就能做出的判断」。书中认为系统一容易出错，TypeSafe 的观点是，这类模型可以被训练得比其他方案更可靠。
需要注意的是，「不会幻觉」指的是答案的格式永远正确，并不代表判断一定正确。模型仍然可能在 3 个选项中很自信地选错。
Jev 这个名字来自英国经济学家 [[William Stanley Jevons]]，也就是「[[杰文斯悖论]]」的提出者。杰文斯悖论指的是，当一种资源的利用效率提升、使用成本下降之后，它的总消耗量反而会增加。蒸汽机效率提升之后，煤炭的消耗不降反升。TypeSafe 认为机器智能也会走同样的路：当判断变得足够便宜和快速，软件中使用 AI 的地方会成倍增加。
TypeSafe AI 的创始人是 Diogo Almeida，他曾在 [[OpenAI]] 参与指令遵循方向的研究，这些工作后来成为 [[ChatGPT]] 背后的研究基础（InstructGPT / RLHF）。公司在隐身状态下研发了 2 年才对外发布产品，据媒体报道，公司由 DCVC 领投完成了 4000 万美元融资。
以下数据来自 TypeSafe 官方：
在我们的自动化流程当中，有大量这样的判断，比如这个任务要交给哪个模型处理、这封邮件是否紧急、这个工单要转给哪个部门。过去这些判断要么写成固定的规则，要么交给 LLM，前者不够灵活，后者又慢又贵，Jev 正好填补了两者之间的空白。
官方把 Jev 的用途归为 4 类：
官方文档中还有 20 多个 Cookbook 示例，比较有代表性的有：
从这些例子可以看出，Jev 并不是要取代 LLM，而是和 LLM 配合使用：LLM 负责生成和复杂推理，Jev 负责其中大量快速、便宜的判断。
Jev 的调用依赖两个部分：
然后 Jev 就能直接返回结构化的答案。
一次请求可以同时包含多个问题，每个问题都会针对同一个 state 并行、独立地进行判断，所以多加几个问题几乎不会增加响应时间，问题之间也不会互相干扰，不会出现 LLM 上下文越长效果越差的「上下文腐烂」问题。
Jev 支持 3 种问题类型：
3 种问题可以在同一次 API 调用中混合使用。
官方 Quick Start 中的例子，用一条客服工单同时问了 3 个问题：交给哪个部门处理、用户有多不满、是否紧急。
{
"model": "jev-latest",
"state": "Hi, I've been trying to connect my Stripe account for 3 days and the integration keeps failing. I'm losing sales. Please help ASAP.",
"questions": {
"department": {
"type": "choice",
"instructions": "Which team should handle this",
"criteria": {
"billing": "Payment or subscription issues",
"technical": "Bugs or integration problems",
"sales": "Pricing or account questions"
}
},
"frustration": {
"type": "score",
"instructions": "How frustrated the customer appears",
"criteria": [
"Calm, just stating facts",
"Frustrated but civil",
"Very angry, strong language"
]
},
"is_urgent": {
"type": "noul",
"instructions": "The message conveys urgency or time-sensitivity"
}
}
}
返回结果：
{
"model": "jev-1.13.0",
"answers": {
"department": {
"type": "choice",
"choice": "technical",
"confidence": 0.78,
"probabilities": {"technical": 0.85, "sales": 0.0, "billing": 0.15}
},
"frustration": {
"type": "score",
"score": 1.0,
"confidence": 1.0,
"legend": {
"0": "Calm, just stating facts",
"1": "Frustrated but civil",
"2": "Very angry, strong language"
},
"probabilities": {"0": 0.0, "1": 1.0, "2": 0.0}
},
"is_urgent": {"type": "noul", "noul": 1.0}
},
"usage": {"input_tokens": 392, "output_tokens": 65}
}
department 判断为 technical（概率 0.85，置信度 0.78），frustration 评分为 1.0，即「Frustrated but civil」，is_urgent 为 1.0。model 字段返回的是实际使用的版本号，这次请求消耗了 392 个输入 Token，而输出 Token 是免费的。
也可以使用官方的 Python SDK（需要 Python 3.10 及以上版本）：
pip install typesafe-sdk
from typesafe_sdk import Choice, Noul, Score, TypeSafeClient
# 默认从环境变量 TYPESAFE_API_KEY 读取 API Key，默认模型为 jev-latest
client = TypeSafeClient()
ticket = "Hi, I've been trying to connect my Stripe account for 3 days and the integration keeps failing. I'm losing sales. Please help ASAP."
response = client.system_one(
state=ticket,
questions={
"department": Choice(
instructions="Which team should handle this",
criteria={
"billing": "Payment or subscription issues",
"technical": "Bugs or integration problems",
"sales": "Pricing or account questions",
},
),
"frustration": Score(
instructions="How frustrated the customer appears",
criteria=[
"Calm, just stating facts",
"Frustrated but civil",
"Very angry, strong language",
],
),
"is_urgent": Noul(
instructions="The message conveys urgency or time-sensitivity",
),
},
)
print(response.answers["department"].choice) # "technical"
print(response.answers["frustration"].score) # 1.0
print(response.answers["is_urgent"].noul) # 1.0
Noul 用来回答一个「是或否」的问题，或者判断一句陈述是否成立，比如「这条消息是否在申请退款」「这份简历是否有 Python 经验」。
请求参数：
type：固定为 noul
instructions：要判断的问题或陈述criteria：可选，用 true 和 false 两个字段分别描述什么情况算「是」、什么情况算「否」返回结果只有一个 0 到 1 之间的数字 noul，表示答案为「是」的概率，0 表示否，1 表示是。因为一个数字已经同时描述了两种结果，所以 Noul 没有单独的 confidence 字段。
{"type": "noul", "noul": 0.99}
使用建议：
instructions 也可以传入对象，比如把一条待比对的数据库记录和问题一起传进去，一次请求就能用多个 Noul 把一份简历和多条记录做查重。
Choice 让 Jev 从一组事先定义好的选项中选出一个，适合分类和路由，比如工单分配给哪个部门、商品属于哪个类目、代码是哪种编程语言。Choice 是单选，不支持多选。
请求参数：
type：固定为 choice
instructions：问题本身criteria：选项名到选项描述的映射，模型会同时看到选项名和描述；如果选项名本身已经足够清楚（比如 calm、frustrated、angry），描述可以为 null
一个问题最多可以有 255 个选项，每多一个选项只多消耗几个 Token。
返回结果包含 3 个字段：
choice：概率最高的选项probabilities：所有选项的概率分布，加起来等于 1confidence：0 到 1 之间，根据概率分布的形状计算，只有一个明显的峰值时置信度高，概率分散在多个选项上时置信度低{
"type": "choice",
"choice": "returns",
"confidence": 1.0,
"probabilities": {"returns": 1.0, "shipping": 0.0, "billing": 0.0}
}
官方举了一个含糊的例子：一张工单同时提到了配送延迟、尺码不对和重复扣款，这时 department 在 returns（0.61）和 billing（0.35）之间摇摆，置信度只有 0.42。代码可以根据这些数字做进一步处理：
使用建议：
other 或「以上都不是」的兜底选项，否则模型只能在不合适的选项里硬选一个what、not_for、examples 等字段的对象Score 让 Jev 在一个有顺序的等级上给出评分，比如 Bug 的严重程度、用户的不满程度、候选人的经验水平。和 Choice 的区别在于，Score 的选项有高低顺序，结果可以落在两个等级之间。
请求参数：
type：固定为 score
instructions：问题本身criteria：按从低到高排列的等级描述，至少 2 个、最多 10 个，按顺序从 0 开始编号返回结果：
probabilities：每个等级的概率，加起来等于 1score：每个等级编号乘以对应概率后求和，得到的加权平均值legend：等级编号和描述的对应关系confidence：概率越集中在一个等级上，置信度越高以官方的 Bug 严重程度为例，3 个等级分别是「只影响外观」「功能受损但有替代方案」「阻塞且没有替代方案」，返回的概率分别是 0、0.57、0.43，所以 score 为 0×0 + 1×0.57 + 2×0.43 = 1.43，置信度 0.35。
{
"type": "score",
"score": 1.43,
"confidence": 0.35,
"probabilities": {"0": 0.0, "1": 0.57, "2": 0.43}
}
置信度偏低通常有 3 个原因：等级之间在这个内容上有重叠；一个问题同时在衡量多件事；内容本身没有提供足够的信息。
使用建议：
["0","1","2"] 作为等级时，一个按钮错位的问题得到 0.55 分、置信度 0.33；换成文字描述之后得到 0 分、置信度 1.0what、examples 字段的对象，补充一个相关的例子能明显提升置信度多个 Score 可以组合成一个综合评分：先把每个 score 除以最高等级编号（len(criteria) - 1）归一化到 0 到 1，再在代码中加权求和，官方称之为 Composite scoring 模式。这样当业务优先级变化时，只需要调整代码里的权重系数，而不用重写 Prompt。
| 类型 | 适用场景 | 选项特点 | 返回值 |
|---|---|---|---|
| Noul | 是否判断、规则检查、守门 | 只有是和否 | 为「是」的概率 |
| Choice | 分类、路由、打标签 | 多个选项，没有顺序 | 选中项、概率分布、置信度 |
| Score | 打分、分级、排序 | 多个等级，有高低顺序 | 加权分数、概率分布、置信度 |
复杂的判断不要塞进一个问题里。比如不要直接问「给这个创业项目打分」，而是拆成市场规模、技术可行性、差异化等多个独立的问题，再在代码里组合结果。这也是 Jev 和 LLM 使用思路上最大的不同：LLM 把逻辑写在 Prompt 里，Jev 把逻辑留在代码里。
直接在官网 Playground 中在线体验，或者创建 API Key，并编写代码使用。
每个新注册的账号，添加支付方式之后拥有 5 美元的体验额度。按照每百万输入 Token 0.042 美元计算，5 美元大约可以处理 1.19 亿个输入 Token，以 Quick Start 中那个 392 Token 的请求为例，可以调用约 30 万次，用来测试完全足够。
官方文档提供了 4 种上手方式，可以按照自己的习惯选择。
不写代码的话，最快的方式是 Playground：
Playground 适合在正式写代码之前，先验证问题的措辞和选项的描述是否合适。
在控制台的 API Keys 页面 创建 API Key，然后用任意语言发送 POST 请求即可：
export TYPESAFE_API_KEY="your-api-key"
curl -X POST https://api.typesafe.ai/v1/systemone \
-H "Authorization: Bearer $TYPESAFE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"state": "Hi, I have been trying to connect my Stripe account for 3 days and the integration keeps failing. Please help ASAP.",
"model": "jev-latest",
"questions": {
"urgency": {
"type": "noul",
"instructions": "Does this message express urgency?"
}
}
}'
可以通过 GET https://api.typesafe.ai/v1/models 查看当前账号可以使用的模型。目前可用的模型是 jev-1.13.0，另外有两个别名：
jev-latest：最新的正式版本，也是 SDK 的默认值jev-preview：最新的预览版本，目前和 jev-latest 指向同一个模型别名会随着新版本发布而变化，模型的判断结果也可能随之改变。如果已经针对某个版本调好了置信度阈值，建议在生产环境中固定使用具体的版本号，比如 jev-1.13.0，再按照自己的节奏升级。每次响应中的 model 字段会返回实际使用的版本号，可以记录到日志中。
官方提供了 Python 和 JavaScript/TypeScript 两个 SDK。
# Python，需要 Python 3.10 及以上
pip install typesafe-sdk
# 或者
uv add typesafe-sdk
# JavaScript / TypeScript
npm install @typesafe-ai/sdk
两个 SDK 都会自动从环境变量 TYPESAFE_API_KEY 读取 API Key，默认使用 jev-latest 模型。Python SDK 同时提供同步的 TypeSafeClient 和异步的 AsyncTypeSafeClient，并且内置了重试机制，遇到限流时会按照 retry-after 自动退避重试。具体的调用方式见上文的请求示例。
TypeSafe 还提供了一个 Agent Skill，可以让 [[Claude Code]]、[[Codex]] 等 Coding Agent 了解 Jev 的 API、3 种问题类型和常见的架构模式，从而生成正确的集成代码。
Skill 的源码托管在 GitHub 的 typesafe-ai/skills 仓库中，核心文件是 skills/typesafe-ai/SKILL.md。下面 3 种安装方式任选其一即可，同时使用多种方式会装出重复的副本。
在 Claude Code 中，以插件的形式安装，先添加插件市场，再安装插件：
claude plugin marketplace add typesafe-ai/skills
claude plugin install typesafe@typesafe-ai
在 Codex、Cursor 等其他 Agent 中，使用 skills.sh 的命令行工具安装，执行后会提示选择要安装到哪个 Agent：
# 默认安装到当前项目
npx skills add typesafe-ai/skills --skill typesafe-ai
# 加上 -g 安装到全局，所有项目都可以使用
npx skills add typesafe-ai/skills --skill typesafe-ai -g
也可以手动安装，把仓库中整个 skills/typesafe-ai 目录（包括其中的参考文件）复制到 Agent 的 skills 目录中，以 Claude Code 为例：
git clone https://github.com/typesafe-ai/skills.git /tmp/typesafe-skills
cp -r /tmp/typesafe-skills/skills/typesafe-ai ~/.claude/skills/
如果懒得自己敲命令，还可以把下面这段话直接发给 Coding Agent，让它自己完成安装：
Install the TypeSafe skill. If you're in Claude Code, run `claude plugin marketplace add typesafe-ai/skills`, then `claude plugin install typesafe@typesafe-ai`. If you're in another agent, run `npx skills add typesafe-ai/skills --skill typesafe-ai` and select your agent. Use one installation method. You can read the skill directly at https://github.com/typesafe-ai/skills/blob/main/skills/typesafe-ai/SKILL.md (raw: https://raw.githubusercontent.com/typesafe-ai/skills/main/skills/typesafe-ai/SKILL.md). Then use the TypeSafe skill when working on this project.
TypeSafe 的 API 还在快速迭代，Skill 版本过旧时，Agent 可能会编造出不存在的请求或响应字段，所以需要定期更新。
Claude Code 插件的更新命令：
claude plugin marketplace update typesafe-ai
claude plugin update typesafe@typesafe-ai
更新之后重启 Claude Code，或者在会话中执行 /reload-plugins 重新加载。也可以在 /plugin 菜单中依次选择 Marketplaces → typesafe-ai → Enable auto-update 开启自动更新。
通过 skills.sh 安装的，执行：
npx skills update
手动安装的，用 GitHub 上最新的 skills/typesafe-ai 目录整个替换掉旧目录即可。
安装之后，在 Claude Code 中可以直接输入斜杠命令调用：
/typesafe:typesafe-ai
在其他 Agent 中，或者 Agent 没有自动加载 Skill 时，在提示词中明确写上「use the TypeSafe skill」即可。如果仍然没有生效，检查安装时选择的是否是当前使用的 Agent，然后重启 Agent。
官方给出了几个可以直接使用的提示词。
找出项目中适合使用 Jev 的地方，让 Agent 扫描现有项目，寻找可以用智能判断代替复杂解析逻辑或脆弱代码的位置：
Using the TypeSafe skill, explore the project and find opportunities for using
intelligent judgement to stand in for complex parsing or other fragile code.
让 Agent 用真实的 API 做实验。先把 API Key 导出到环境变量，Agent 会自己发送一些低成本的测试请求，再根据结果给出修改方案：
export TYPESAFE_API_KEY="your-api-key"
Using the TypeSafe skill, run some experiments using the TypeSafe API key that I've
exported to `TYPESAFE_API_KEY`. Propose changes based on the most promising results.
对照官方 Cookbook 重构代码，让 Agent 检查现有代码是否有可以套用的官方示例：
Using the TypeSafe skill, analyze my code and see if there are any applicable
cookbooks (https://console.typesafe.ai/docs/cookbooks) that show how I could
refactor my code to be less fragile or complex.
从零开始写一个小工具，比如一个从多个维度评估文档的命令行程序：
Let's build a simple CLI that uses the TypeSafe API to evaluate a set of supplied
documents on multiple dimensions. Use the TypeSafe skill to understand how to use
the TypeSafe API and how to structure the system. Ask me questions about what kinds
of documents I want to evaluate and on what dimensions.
需要注意的是，Jev 本身并不能作为 Coding Agent 背后的模型。它不能写代码、不能对话、也不能调用工具，不存在把 Claude Code 的模型换成 jev-latest 这种用法。正确的思路是继续用 LLM 写代码，而在写出来的程序里调用 Jev 做判断。
官方还给了几条使用建议：把所有问题和阈值常量集中放在一个文件里，方便人工审查；Agent 并不擅长写问题，问题的措辞最好自己参与修改；不要轻易相信 Agent 的判断，让它用真实请求去验证假设。
和 LLM 模型一样，Jev 也一样会犯错。官方在文档中专门列出了当前版本 jev-1.13 已知的「锯齿」（jaggedness），也就是那些它做得不好的地方，并说明其中很多会在后续版本中改进。
Jev 的能力有明确的边界，不能生成文字，不能做数学推理，也无法比较日期。总的来说，Jev 擅长常识性的语义判断，但不擅长需要多步推理、数字精度的任务，而且对问题的理解非常字面化。
| 场景 | 表现 | 建议做法 |
|---|---|---|
| 数学和计数 | 算不准、数不清，看不懂十六进制颜色、RGB 这类数字表示，Score 的分数也不能用来插值出精确数值 | 计算和计数放在代码里 |
| 日期比较 | 把日期当文本，判断先后、间隔、是否在区间内都不可靠 | 用 Choice 提取年月日，在代码中比较 |
| 间接推理 | 双重否定、多跳推理时准确率下降 | 问题写得直接，在 state 中用字段名指明看哪里 |
| 无关上下文过多 | 无关内容成为干扰项，越多越不准 | 先在代码中过滤，只传问题需要的字段 |
| 对抗性内容 | 注入的指令、误导性表述会影响结果，同样存在 [[Prompt Injection]] 风险 | 写清 criteria，上线前测试边界情况 |
| 问题与描述矛盾 | instructions 和 criteria 意思不一致时判断混乱 | 让两者的表述保持一致 |
| 问题之间的换算 | 同一问题的正反两种问法，概率相加不等于 1（官方示例 0.72 + 0.47 = 1.19），Noul 和 Choice 的数值也不能互相比较 | 不依赖问题之间的数学关系，阈值不跨类型复用 |
| 生成文本 | 效果差且很慢 | 用正则或 LLM 找出候选项，让 Jev 从中选择 |
429 Too Many Requests。由于需求量很大，官方表示这个限制随时可能动态调整，更高的额度需要联系销售购买企业方案还有两点值得注意。
第一，「校准」是统计意义上的。Jev 返回的概率在大量预测上是准确的，比如所有 0.8 的判断里大约 80% 是对的，但这并不保证某一个具体的答案是正确的。同样，高置信度也不等于答案正确。
第二，目前公开的速度、成本和准确率数据主要来自 TypeSafe 官方，演示也多是在模拟环境中完成的，还缺少公开基准测试的成绩和大规模生产环境的验证。
官方文档最后总结了 4 条应该避免的做法：
总结下来，使用 Jev 的正确姿势是：把确定性的逻辑（计算、比较、计数、流程）留在代码里，只把「一个懂行的人几秒钟就能做出的判断」交给 Jev，再通过置信度决定是否自动执行，或者交给人工、交给更强的推理模型处理。
2026-09-07 13:00:00
同时使用 Claude Code，Codex，Pi，OpenClaw 等等 Agent 工具时有一个非常尴尬的状况，就是不同的 Agent 工具维护了不同的配置格式，如果要配置 MCP server 就需要分别到不同的配置文件中定义，相同的配置散落在系统的各个角落中。同一份 API Key 也需要重复粘贴到不同的配置中，更麻烦的是如果一旦有更新或者 API Key 变动就需要重复修改多个地方，我之前还调查过如何[[跨平台管理 MCP]]，主要的思路还是通过脚本和同步来对齐配置，但本质上还是在管理多个副本，直到我看到了 Executor 这个项目。
Executor 项目的目的是为了简化各个 Agent 配置，在 Agent 和外部 API 之间做一层代理。集成只加一次，凭据只给一次，权限策略只设一次，然后所有 MCP 兼容的客户端都指向这一层，共享同一个工具目录。项目地址的作者是 Rhys Sullivan，之前在 Vercel、Microsoft、Epic Games 待过。
先说清楚 Executor 不是什么。它不是又一个 MCP server，也不是某个特定服务的封装。它的定位是集成层，或者说 MCP 网关，README 里的原话是 “The missing integration layer for AI agents”。
今天 agent 生态的现状是：每个客户端都是一座孤岛。你在 Claude Code 里接了 Linear 的 MCP server，Cursor 想用就得再接一遍；你给某个 agent 配了公司内部 API 的 token，另一个 agent 想调同一个接口，你得再找一遍那个 token 存在哪。这套模式在只有一个 agent 的时候完全没问题，但当你手上同时跑着桌面客户端、终端 CLI、云端 agent 的时候，配置的重复度和凭据的扩散范围就开始失控了。
更深一层的问题是权限。MCP 协议本身没有定义工具级别的授权模型，一个 MCP server 暴露出来的所有工具，对客户端来说要么全都能调，要么整个 server 不接。你没有办法说”这个 server 的读操作随便调，写操作必须先问我”。实际使用中这个粒度是不够的，尤其当 agent 有能力调用会产生真实副作用的接口时。
Executor 把这三件事——集成定义、凭据存储、权限策略——从客户端里抽出来，放到一个独立的服务里，然后通过 MCP 协议统一暴露出去。
Executor 的设计很简单，只有三个概念：
Integration 是集成本身，也就是你想接入的东西的定义。Executor 支持 MCP server、OpenAPI 规范、GraphQL 接口，以及 Google Discovery。README 里有一句话我觉得概括得很好：只要能用 JSON Schema 描述，它就能成为一个 integration。这也意味着接入方式非常直接，你有一份 OpenAPI 的 YAML 或者 JSON，扔进去就完事了，不需要为它单独写一个 MCP server 的包装层。这一点其实很关键，因为现实中大量内部服务都有 OpenAPI 文档，但几乎没有人会为它专门写 MCP server。
Connection 是集成的一个已配置实例。这里的设计有点意思：integration 和 connection 是一对多的。同一个 GitHub 的 OpenAPI 定义，你可以建三个 connection，分别用不同账号的 token；同一个内部 API，你可以建 staging 和 production 两个 connection，指向不同的 baseUrl。凭据是挂在 connection 上的，而不是挂在 integration 上。
Policy 是每个工具的权限级别，一共三档：allow 直接放行，require approval 调用时暂停等人工批准，block 完全禁止。关键在于默认值不是手工一个个点出来的，而是从规范里推导的。文档给的例子是 OpenAPI：GET 这类只读操作默认允许，写操作可以设成需要批准。这个默认值的推导逻辑很实用，因为一份稍具规模的 OpenAPI 文档动辄上百个 endpoint，指望人工逐个设策略是不现实的，能按 HTTP 方法自动分出安全和危险两档，剩下的手工微调量就小得多了。
Executor 对外的形态就是一个 MCP endpoint。agent 说 MCP，Executor 在后面把请求路由到具体的集成上：对上游 MCP server 说 MCP，对 OpenAPI 和 GraphQL 说 HTTP，然后把结果原路返回。
这个代理结构带来的第一个好处是配置的解耦。因为客户端只认识 Executor 这一个端点，你在 Executor 里增删改上游服务，客户端完全不需要动。加了一个新集成，agent 那边自动就能看到新工具，不需要重启、不需要改配置文件、不需要在 5 个客户端里重复这个动作。这一点对我来说是最直接的收益，我加一个内部 API，Claude Code 和 Cursor 同时就有了。
第二个好处更重要，是凭据的隔离。文档里的说法是 credentials stay out，凭据存在 Executor 持有的 connection 上，在实际发起上游调用的那一刻才附加到请求里。agent 从头到尾看不到 token，也就不存在 token 意外进入模型上下文、被写进日志、或者被 prompt injection 套出来的风险。如果你的 agent 跑在沙箱里，或者是一个你不完全信任的第三方客户端，这个隔离是有实际意义的。
第三是策略在每次调用时统一执行。不管请求从哪个 agent 来，走的都是同一套 policy 判断。你不需要在每个客户端里分别配一遍权限，也不会出现某个客户端漏配导致权限失控的情况。新接入的上游服务自动继承同一套策略机制。
需要提醒一点，大部分 MCP 客户端只在启动时加载 server 列表，所以第一次把 Executor 接进去之后，通常需要重启客户端或者开一个新会话，工具才会出现。这个坑文档里明确提到了，我也确实踩了一次，以为是配置写错了。
Executor 提供了 4 种运行形态，功能完全一致，区别只在打包方式。
本地 CLI 是最轻的方式，npm install -g executor 装上，然后 executor install 把它注册成常驻后台服务，executor web 打开网页控制台。这个后台服务会跨重启保持运行，如果你只想临时跑一下不留痕迹，用 executor web --foreground 起一个前台进程就行。默认监听 127.0.0.1:4788，端口被占用时会自动挑一个空闲端口。需要 Node.js 20 以上。
桌面应用是同一个运行时套了个原生壳，Mac、Windows、Linux 都有，适合日常桌面环境；CLI 更适合无头服务器。
Executor Cloud 是官方托管版本，有免费额度，什么都不用装，直接登录、加集成、把 agent 指向托管端点。如果你用的是云端 agent，这条路是唯一能走通的，因为云端 agent 连不到你本机的 127.0.0.1。
自托管有两条路径。[[Docker]] 版本是 ghcr.io/usefulsoftwareco/executor-selfhost:latest，单个容器里打包了 API、MCP、认证、代码执行和 Web UI，数据落在一个 SQLite 文件里，暴露 4788 端口，零配置起步。[[Cloudflare]] 版本是部署到你自己账号下的一个 Worker，用 Cloudflare Access 做认证，用 D1 做存储。
选择的判断标准其实很清晰：如果所有 agent 都在本机，用本地版本，桌面环境选 App，服务器选 CLI；如果需要多台机器或者云端 agent 访问同一份目录，就上托管或自托管。我自己的用法是 Docker 自托管，跑在家里的 NAS 上，这样笔记本、台式机和几个服务器脚本共享同一份集成目录，同时数据完全在自己手上。
接入客户端用的是 add-mcp 这个工具，它会自动检测你当前的 MCP 客户端并写入配置：
npx add-mcp http://127.0.0.1:4788/mcp --transport http --name executor
如果要走 stdio 传输：
npx add-mcp "executor mcp" --name executor
添加集成可以在 Web UI 里点 Add Integration，也可以走 CLI。这里有个细节值得注意：当 OpenAPI 文档里的 servers 字段用的是相对路径时，需要显式传 baseUrl，否则请求不知道该发到哪里。很多内部服务生成的 OpenAPI 文档都有这个问题，第一次接的时候容易卡住。
日常会用到的 CLI 命令大概是这几个：
executor tools search <query> # 在目录里搜工具
executor call <path...> # 直接调用某个工具
executor tools integrations # 列出所有集成
executor tools describe <tool> # 查看工具的详细定义
executor resume --execution-id <id> # 恢复一次被暂停的执行
executor daemon status # 查看后台服务状态
executor resume 对应的就是 policy 里 require approval 那一档，调用被挂起之后用它继续。这些命令都会自动拉起本地 daemon，不需要手动先启动。
如果要在自己的代码里用，官方提供了 TypeScript SDK，同时给了 Promise 和 Effect 两套 API：
import { createExecutor } from "@executor-js/sdk/promise";
import { openApiPlugin } from "@executor-js/plugin-openapi/promise";
用下来我觉得它最适合的场景，是你手上有多个 agent 客户端，并且有一批自己的、非公开的 API 需要接进去。如果你只用一个 Claude Code，接的也都是现成的公开 MCP server，那 Executor 引入的这一层收益不大，反而多了一个需要维护的服务。它的价值随着 agent 数量和自有 API 数量的增长而放大。
OpenAPI 直接导入这条路是我认为最被低估的能力。写一个 MCP server 需要理解协议、搭脚手架、处理传输层，而扔一份 OpenAPI 文档进去是零成本的。公司内部服务基本都有 Swagger 文档，这意味着让 agent 接触内部系统的门槛一下子降到了几乎为零。当然这也是双刃剑，接得越容易，就越需要认真对待 policy 那一层。
关于 policy ，默认按 HTTP 方法分档。但是 GET 也可能是危险的，比如一个导出全量用户数据的 GET 接口；POST 也可能完全无害，比如一个搜索接口。所以自动推导出来的默认值应该被当成待审阅的草稿，而不是最终配置。特别是刚导入一份大的 OpenAPI 文档之后，值得花点时间把明显敏感的接口手动降级。目前文档里对批准流程的细节说得不多，谁能批准、请求怎么呈现、有没有超时、批准是否会被记住，这些都还不清楚，需要自己试。
另一个需要清醒认识的是，加这一层意味着多了一个单点。Executor 挂了，所有 agent 的所有工具一起挂。本地跑还好，如果是团队共享的自托管实例，这个可用性问题得认真考虑。相应地，它也成了一个高价值目标——一个集中存放了你所有 API 凭据的服务，本身的安全边界需要被认真对待，尤其是自托管暴露到公网的情况。Cloudflare 版本用 Cloudflare Access 做认证这个选择，某种程度上也是在回应这个问题。
从生态位上看，Executor 经常被拿来和 Composio 这类服务比较，核心差异在于开源和可自托管。Composio 是托管的商业服务，你的凭据存在它那里；Executor 你可以完全跑在自己的机器或者自己的 Cloudflare 账号里。对于凭据敏感的场景，这个差异是决定性的。
我觉得 Executor 真正抓住的，是 agent 生态里一个还没被认真对待的结构性问题：随着一个人同时使用的 agent 从 1 个变成 5 个，集成配置的复杂度不是线性增长，而是集成数乘以客户端数的乘积增长。用同步配置文件的方式去对抗这个乘法，只能缓解，不能解决。把集成提取成一个独立的、被所有客户端共享的层，才是从根上消掉那个乘数。
它现在还很年轻，2026 年才起步，文档里不少地方——尤其是批准流程和沙箱执行——还没写透，policy 模型也还比较粗。但方向我认为是对的。MCP 协议解决了 agent 和工具之间的通信标准，但没有解决工具的管理、认证和授权，那部分空白总归需要有东西来填。Executor 是目前我看到的填法里比较完整的一个：概念足够少，部署方式足够多，而且完全开源可自托管。
2026-08-21 13:00:00
昨天我把一块装着 [[Proxmox VE]] 系统的硬盘从之前的 SER8 拆下来，插到 4 盘位的 Me Pro 上，本以为开机就能继续用，结果卡在了最基础的一步：Me Pro 的物理网口和我原来的网口对不上，物理网口变更了名字导致无法上网。屏幕上 PVE 的控制台在闪，ip addr 里却无法找到两个物理网口，Web 管理界面自然也打不开。
在和 Claude 交流寻找解决方案的过程中，我看到 Claude 说「用手机 USB 共享网络」，先确保 PVE 有网络，然后利用网络更新 Kernel。我开始还有点疑惑，这样也可以，但是手边正好有一台 Pixel，顺手就用 Type-C 数据线链接了，然后在 Android 端切换到 USB tethering，在 PVE 查看，立马就能看到多出一张网卡，利用 dhclient enxxx 就可以获取 IP 地址，立马就能 ping 通网络。
这个功能是，当手机自己连着 Wi-Fi 的时候，它同样可以把这份 Wi-Fi 网络通过 USB 线转发出去。换句话说，一根数据线加一台安卓手机，就等价于一张即插即用的 USB 无线网卡。
这件事让我开始重新审视抽屉里那几台退役的安卓手机。它们其实是完整的 ARM 计算机：有 CPU、有内存、有存储、有电池（相当于自带 UPS）、有 Wi-Fi 和蓝牙、有摄像头和屏幕、有 USB OTG。我们只是习惯性地把它们当作「淘汰的手机」，而不是「一台便宜的、带屏幕的、待机功耗只有几瓦的小型服务器」。
要理解为什么这招好用，得先知道手机在 USB 那端到底扮演了什么角色。安卓设备通过 USB 连接电脑时，可以以不同的 USB Gadget 身份出现：MTP 模式下它是一个媒体设备，ADB 模式下它是一个调试设备，而打开 USB 网络共享之后，它把自己声明成了一个 USB 网络适配器。
具体用的协议一般是 RNDIS（Remote NDIS，微软定义的一套通过 USB 承载以太网帧的规范），近几年不少设备也改用了更标准、效率更高的 CDC-NCM。这两种协议在 Linux 内核里都有现成的驱动，分别是 rndis_host 和 cdc_ncm，属于早就编译进主流发行版内核的东西。所以主机侧不需要装任何厂商驱动，插上线之后内核就会枚举出一张新的以太网接口，传统命名是 usb0，在启用了 systemd 可预测网卡命名的系统上则是 enx 加上 MAC 地址的形式，比如 enx0a1b2c3d4e5f。
有意思的是手机这一侧。它并不是简单地做一个透明网桥，而是实实在在跑了一套小型路由：手机在这个 USB 网络接口上给自己分配 192.168.42.129 这个地址，同时启动一个 DHCP 服务，把 192.168.42.0/24 网段的地址发给通过 USB 连过来的主机，然后对出站流量做 NAT，把它们转发到当前的上游链路。这个上游链路可以是移动数据，也可以是手机正连着的 Wi-Fi。安卓的 tethering 框架并不关心上游是什么，它只负责把默认路由指向那条可用的链路。这正是「手机变无线网卡」的关键：Wi-Fi 进，USB 出。
顺带一提，Wi-Fi 热点用的是 192.168.43.0/24，蓝牙共享用的是 192.168.44.0/24，这三个网段是安卓 tethering 的固定约定。知道这个在排查问题时很有用，看到 192.168.42.129 这个网关地址，你就能确定链路走的是 USB 而不是别的。
PVE 基于 Debian，所以下面的步骤在绝大多数 Debian 系发行版上通用。先把线插上，在手机的设置里找到「网络和互联网 - 热点与网络共享 - USB 网络共享」并打开。注意这个开关往往是灰的，直到系统检测到 USB 数据连接才会变为可点，而且它要求你用的是数据线而不是只能充电的线，这个坑我踩过不止一次。
打开之后回到主机，先确认内核有没有认出设备：
lsusb
ip link
dmesg | tail -20
正常情况下 ip link 里会多出一张 usb0 或 enx 开头的接口，dmesg 里能看到类似 rndis_host ... register 'rndis_host' at usb-0000:00:14.0-2, RNDIS device, 0a:1b:2c:3d:4e:5f 的日志。如果什么都没出现，先手动加载一次驱动：
modprobe rndis_host
modprobe cdc_ether
modprobe cdc_ncm
接口出来之后，临时用的话一条命令就够了：
ip link set usb0 up
dhclient usb0
拿到地址后 ip route 里会出现指向 192.168.42.129 的默认路由，此时 PVE 的 Web 界面就能通过这个新地址访问了。如果你希望它持久生效，可以在 /etc/network/interfaces 里加一段：
allow-hotplug usb0
iface usb0 inet dhcp
allow-hotplug 而不是 auto 是有讲究的，手机不一定一直插着，用 auto 会让开机时因为等待这张不存在的网卡而拖慢启动。
有一点需要提醒：这套方案更适合救急和临时维护，不适合长期作为服务器的主链路。手机会不断被主机供电，长时间维持在满电状态对锂电池不友好，而且系统更新、电话来电、后台清理都可能中断这条链路。我的做法是把它当成「带外管理通道」，用它把机器救活、把正式网络配置好，然后拔掉。
PVE 的特殊之处在于它既是宿主机也是虚拟化平台，所以这张「手机网卡」有两种用法，要根据目的选择。
第一种是留在宿主机上，也就是我前面救急时用的方式。适合的场景是宿主机自己失联了，你需要一条通道进入 Web 管理界面。配置就是上面那几条命令，不需要动虚拟化相关的东西。如果你还希望虚拟机也能借道上网，不要试图把 usb0 桥接进 vmbr0，这条路走不通。原因在于 RNDIS 接口只会为它对面的那一个 MAC 地址学习和转发，安卓侧不接受来自多个 MAC 的帧，桥接之后虚拟机发出的包能出去但回不来。正确的做法是在宿主机上做 NAT：
sysctl -w net.ipv4.ip_forward=1
iptables -t nat -A POSTROUTING -o usb0 -j MASQUERADE
这样挂在 vmbr0 上的虚拟机把网关指向宿主机，就能通过手机出网。要持久化的话把 net.ipv4.ip_forward=1 写进 /etc/sysctl.d/，NAT 规则用 iptables-persistent 保存。
第二种是把手机整个直通给某台虚拟机，比如你想让 OpenWrt 或者软路由虚拟机直接管理这条上行链路。在 PVE 的 Web 界面里，选中虚拟机进入硬件页，添加 USB 设备，这里会给出两种绑定方式：按厂商和设备 ID，或者按 USB 端口。
对安卓设备一定要选按端口。这是个容易忽略但很关键的细节：手机在切换 USB 模式时会重新枚举，Product ID 跟着变，比如 Pixel 在纯充电、MTP、ADB、网络共享几种状态下报的 ID 各不相同（Vendor ID 固定是 Google 的 18d1，Product ID 却会在 4ee1、4ee2、4ee7 之间跳）。如果你按 ID 绑定，用户在手机上一点「USB 网络共享」，设备就从虚拟机眼前消失了。按端口绑定则只认物理插口，无论手机怎么切换模式都能保持连接。
命令行的写法是先用 lsusb -t 找到总线和端口号，再挂给虚拟机：
lsusb -t
qm set 100 -usb0 host=1-4
其中 1-4 表示 1 号总线的 4 号端口，100 是虚拟机的 VMID。如果插的是 USB 3 口，可以加上 usb3=1。这个操作支持热插拔，虚拟机不需要重启就能看到新设备，虚拟机内部同样会出现一张 usb0，配置方法和前面完全一致。
两种方式不能同时使用。设备一旦直通给虚拟机，宿主机上的 usb0 就会消失，所以如果你的目的是抢救宿主机本身，老老实实用第一种。
救急之后我顺着这个思路想下去，安卓能做的远不止转发网络。最有想象空间的是 [[Termux]]，它在不 root 的前提下提供了一个相当完整的 Linux 用户空间环境，有自己的包管理器 pkg，能装 Python、Node.js、Go、Rust、git、ffmpeg、nginx、openssh 这些常规工具。你可以在手机上跑一个 sshd，然后从笔记本 ssh 进去，体验和登录一台小型 VPS 没有本质区别。
实际能落地的场景不少：把 [[Syncthing]] 装在旧手机上，它就是一个永远在线的同步节点，比常开一台 NAS 省电得多；用 Termux 跑定时任务抓取数据、做备份；跑一个轻量的下载器，配合外接的 OTG 硬盘当离线下载盒子；甚至可以跑 [[copyparty]] 这类文件服务，把手机的存储变成局域网里的文件共享点。一台闲置的旧机器待机功耗大概在 2 到 5 瓦之间，比树莓派还低，而且自带屏幕和电池。
如果你需要的是更完整的发行版而不只是 Termux 的环境，[[Andronix]] 或者 Termux 自带的 proot-distro 可以在用户态跑起 Debian、Ubuntu、Arch 的根文件系统。性能会因为 proot 的系统调用拦截而打折扣，但对于跑一些依赖 glibc 的软件是够用的。
[[Scrcpy]] 是我用得最频繁的工具之一。它通过 ADB 把一个精简的 server 推到手机上，用 H.264 编码把屏幕流传回电脑，同时把电脑的键鼠事件注入回手机。延迟通常在 35 到 70 毫秒之间，实际体验接近于手机变成了电脑的一个窗口，可以直接用键盘打字、用鼠标操作，还能拖拽文件安装 APK。不需要 root，也不需要在手机上装任何应用。
配合 ADB 还能玩出更多花样。adb reverse tcp:8080 tcp:8080 可以做反向端口转发，让手机上的应用访问到你电脑本地的服务，调试移动端对接本地 API 的时候特别方便。adb shell 则是一个完整的命令行入口，很多在 UI 上被厂商藏起来的设置项，都能通过 settings put 直接改。
Android 14 开始，系统原生支持把手机作为 USB 摄像头使用，插上电脑就会被识别成一个标准 UVC 设备，不需要装任何驱动或者第三方软件。对于手上有旗舰旧机的人来说，这基本是白捡了一个画质远超普通笔记本内置摄像头的网络摄像头。如果你的系统版本较低，DroidCam 或者 IP Webcam 这类应用也能达到类似效果，只是要走 Wi-Fi 或者 USB 转发，多一层配置。
反过来，手机也可以当显示器。spacedesk 这类工具把手机变成 Windows 的扩展屏，出差时带一台平板或者旧手机，就多了一块放监控面板、放文档的副屏。
USB OTG 则打开了另一扇门。旧手机接上 OTG 线之后可以读取 U 盘、SD 读卡器、移动硬盘，也可以接键盘鼠标。我见过有人把旧手机加 OTG 键盘当成一个极简的写作机器，续航一整天。
这两个用法比较小众，但真到需要的时候特别救命。
DriveDroid 可以把手机模拟成一个 USB 存储设备或者光驱，直接把手机里存放的 ISO 镜像挂载给目标电脑启动。这意味着你不需要随身带 U 盘和 [[Ventoy]]，手机里存几个常用的救援镜像就够了。代价是这个功能需要 root 权限，因为它要操作内核的 USB Gadget 配置接口。
另一个是串口控制台。很多服务器、交换机、软路由的管理口是 RJ45 转串口或者 USB 串口，配一根 USB 转 TTL 的线（CH340 或者 FTDI 芯片都行）和一个 OTG 转接头，再装一个 Serial USB Terminal 之类的应用，手机就变成了一台便携的串口终端。机房里不用再抱着笔记本蹲在机柜前，这个体验的差别是巨大的。
PCAPdroid 是一个不需要 root 的抓包工具，它的实现思路很巧妙：利用安卓的 VpnService API 把本机流量引到自己的虚拟接口上，然后落盘成 PCAP 文件。你可以按应用维度过滤，看某个 App 究竟往哪些域名发了请求，也可以把抓到的包导出用 Wireshark 分析。对于研究某个应用的网络行为、排查国内 App 的隐私问题，这是最低门槛的方案。
再加上各种 Wi-Fi 分析工具能看信道占用和信号强度，手机其实是一个相当称职的现场网络诊断设备。装修布网络、排查家里 Wi-Fi 死角的时候，比拿电脑方便太多。
数据线是第一个坑，也是最常见的一个。很多随手机附赠的线或者从充电宝里翻出来的线只有电源触点，没有数据线芯，插上去手机只会显示充电，USB 网络共享的开关始终点不亮。换一根确定能传数据的线，能省掉半小时的排查。
后台被杀是第二个坑。国内定制系统的省电策略非常激进，Termux 里跑着的服务可能在你锁屏几分钟后就被清掉。对策是在系统设置里把这个应用加入电池优化白名单，同时在 Termux 里执行 termux-wake-lock 持有唤醒锁。如果需要开机自启，装一个 Termux:Boot 插件，把启动脚本放到 ~/.termux/boot/ 下。
还有一个比较隐蔽的问题：从 Android 12 开始，系统引入了 phantom process 限制，会主动杀掉应用派生出的子进程，默认上限是 32 个。这对普通应用没影响，但 Termux 里跑多个服务很容易触发，表现为进程莫名其妙消失。可以通过 ADB 关掉这个监控：
adb shell device_config set_sync_disabled_for_tests persistent
adb shell device_config put activity_manager max_phantom_processes 2147483647
需要注意这个设置在部分系统重启后会失效，需要重新执行。
最后是应用来源。Termux 的 Google Play 版本早已停止维护，功能残缺且不再更新，务必从 F-Droid 或者官方 GitHub Release 安装。这类工具类应用普遍存在类似情况，装之前多确认一下渠道。
这次 PVE 迁移带来的最大收获是让我意识到自己对手上工具的想象力实在有限。一台安卓手机被我们默认框定在「打电话、刷视频、拍照」的用途里，但它的底层是一个跑着 Linux 内核的通用计算设备，具备网络栈、USB Gadget、传感器、编解码硬件这些完整的能力。厂商的 UI 只是把这些能力包装成了消费级的形态，而这些能力本身一直都在。
抽屉里那几台旧手机，我打算挑一台出来常年插着电，跑 Termux 加 Syncthing 当同步节点，顺便当成随时可用的救急网卡。它的性能可能不如一台四五百块的迷你主机，但它已经在那里了，边际成本是零。在折腾家庭实验室这件事上，先把已有的东西用起来，往往比再买一件新的更有成就感。
2026-08-16 13:00:00
用 [[Obsidian]] 记笔记这么多年，有一个需求一直没有被很好地解决，那就是在浏览器里直接访问自己的笔记库。Obsidian 官方一直没有推出 Web 版本，过去想要在别人的电脑上、或者在不方便安装客户端的环境里查看和编辑笔记，要么依赖远程桌面这种笨重的方案，要么就只能把笔记渲染成静态网站，牺牲掉编辑能力，或者通过 SSH 登录我的 macOS 通过命令行方式访问。最近我发现了一个叫 Ignis 的开源项目，它的口号非常直接：Run Obsidian as a self-hosted web app. Not remote desktop, an actual web app。它不是远程桌面，而是让 Obsidian 真正跑在浏览器里，体验下来确实让我眼前一亮，这篇文章就来聊聊它。
Obsidian 是一个基于 Electron 的桌面应用，它的编辑器、插件系统、文件访问都建立在 Electron 提供的 Node.js 能力之上，而浏览器出于安全考虑并不提供这些 API，这是官方迟迟没有 Web 版的根本原因。在 Ignis 出现之前，想远程访问自己的笔记库大致有几类办法。
第一类是远程桌面方案，比如用 KasmVNC 或者类似 linuxserver 的 Obsidian 容器镜像，把整个桌面版 Obsidian 的画面通过 VNC 串流到浏览器。这类方案功能上最完整，但体验很差，字体渲染模糊、剪贴板不通、延迟明显，在手机上更是几乎不可用。
第二类是发布类方案，比如 Obsidian Publish、[[Quartz]]、Flowershow 这些工具，把笔记库渲染成静态网站。它们适合对外分享，但本质上是只读的，无法在浏览器里编辑笔记，也用不了任何插件。
第三类是换用天生就是 Web 应用的笔记工具，比如 SiYuan、AFFiNE 之类，但这意味着放弃 Obsidian 的整个插件生态和已经养成的工作流，迁移成本太高。
Ignis 走的是第四条路：它是一个兼容层（compatibility shim），为 Obsidian 所依赖的 Electron API 提供了浏览器端的实现，让原版 Obsidian 的代码直接在浏览器里运行，笔记库则保存在服务器上。值得一提的是，Ignis 本身不包含也不分发任何 Obsidian 的代码和资源，Docker 容器在首次启动时会从 Obsidian 官方源下载程序本体。项目采用 AGPL-3.0 协议开源，作者还专门写了一份 LEGAL.md，援引欧盟软件指令中关于互操作性的条款说明合法性，并明确表示无意损害 Obsidian 官方的商业利益，这种认真程度在同类项目里并不多见。
我最关心的当然是兼容性，毕竟一个残缺的 Obsidian 没有意义。实际情况比我预期的好很多，Obsidian 的核心功能基本都能用：编辑器、Canvas 白板、Bases 数据库视图、命令面板、右键菜单、主题和 CSS 片段都正常工作，绝大多数基于 Obsidian 插件 API 开发的社区插件也能直接加载。图谱视图、大纲这些功能在正确配置 HTTPS 之后也都可用，这一点后面讲部署时会展开。
在 Web 化之后，Ignis 还带来了一些桌面版没有的能力。它支持通过工具栏、右键菜单或者直接拖拽来上传文件到笔记库，也可以把单个文件或整个文件夹打包成 ZIP 下载下来。多仓库支持做得很完整，可以创建、切换、重命名、删除 vault，不同的浏览器标签页甚至可以打开不同的 vault。多个标签页之间通过 WebSocket 实时同步，在一个标签页里的编辑会在一秒内出现在另一个标签页中。另外还有两个很实用的 URL 参数：?workspace= 可以在独立标签页中打开某个保存好的工作区布局，?file= 可以通过 URL 直接打开某篇笔记，这让 Obsidian 的笔记第一次拥有了可以分享给自己其他设备的链接。小屏幕设备上 Ignis 会切换到移动端 UI，手机浏览器里的体验接近 Obsidian 移动客户端。
| 同步方面，官方的 Obsidian Sync 可以在登录的标签页里正常工作，Ignis 还提供了服务端的 Headless Sync，即使浏览器标签页全部关闭，服务器也能继续在后台同步，这个设计解决了 Web 应用”关掉页面就停止工作”的天然缺陷。对于我这种用第三方方案同步的用户，obsidian-livesync 这类走 WebSocket 或 HTTP 的插件也能配置成功，只是要注意一些网络上的细节，后面避坑部分会提到。我在 [[2020-11-23-obsidian-sync-acrose-devices-solution | 我的 Obsidian 笔记跨设备同步方案]] 里梳理过各种同步方式，Ignis 相当于给这些方案又加了一个随时可用的 Web 入口。 |
性能上作者也下了功夫。Ignis 用一次预压缩的 bootstrap 请求就把 vault 信息、元数据树、插件列表全部交付给浏览器，配合索引器预取（indexer pre-fetch）预热内容缓存，让 Obsidian 启动时的索引过程命中缓存而不是反复走网络。服务端用 LRU 缓存控制内存占用，默认 50MB，不会把整个笔记库都加载进内存，这些参数都可以在设置面板里调整。我的笔记库有几千个文件，加载速度完全在可接受范围内。
Ignis 的部署非常简单，官方提供了 Docker 镜像，一个 docker-compose 文件就能跑起来：
services:
ignis:
image: nobbe/ignis:latest
ports:
- "8080:8080"
environment:
# 运行 id 命令查看自己的 uid/gid 并填入
- PUID=1000
- PGID=1000
volumes:
- ./vaults:/vaults
- ./data:/app/data
- obsidian-app:/app/obsidian-app
restart: unless-stopped
volumes:
obsidian-app:
保存为 docker-compose.yml 之后执行 docker compose up -d，首次启动时容器会从官方源下载 Obsidian 和 obsidian-headless CLI，大概需要一两分钟，可以用 docker compose logs -f 观察进度。之后访问 http://localhost:8080，如果 vaults 目录下已经有笔记库会自动加载，否则会打开 vault 管理器引导创建第一个。
有几个部署细节值得注意。PUID 和 PGID 要和宿主机用户匹配，用 id 命令查一下自己的 uid 和 gid 填进去，否则 Ignis 写入的文件归属会出问题。如果笔记库放在 NAS 挂载或者 NFS 上，可以直接把外部目录挂载到 /vaults 下面的子目录；对于 rclone mount、FUSE、NFS、SMB 这类较慢的文件系统，还可以设置 WRITE_COALESCE_MS 环境变量开启写入合并去抖，减少频繁的小写入。
我自己的做法是把 Ignis 指向已有的同步目录，这样桌面版 Obsidian、手机客户端和 Ignis 操作的是同一份数据，Ignis 只是多出来的一个访问入口，不需要改变原有的同步链路。
这一部分是使用 Ignis 之前必须搞清楚的，官方文档也用了醒目的警告来强调。核心有两点：Ignis 没有内置任何身份验证，以及浏览器的安全上下文（secure context）要求。
先说安全上下文。Obsidian 依赖的一些浏览器 API，比如加密和剪贴板相关的接口，只在 HTTPS 或者 localhost 环境下可用。所以如果你通过 http://192.168.1.10:8080 这样的局域网地址裸访问 Ignis，会发现图谱视图、大纲、Sync 等一系列功能默默失效，这不是 bug，而是浏览器的安全策略。解决办法有两类：正经的做法是在前面加一层 TLS，用 Caddy、nginx 或 Traefik 做反向代理（官方 examples 目录里有现成配置），或者用 tailscale serve、Cloudflare Tunnel 这类免证书管理的方案；偷懒的做法是在每个客户端浏览器里把 Ignis 的地址加入安全源白名单，Chromium 系浏览器在 chrome://flags/#unsafely-treat-insecure-origin-as-secure 设置，但这种方式只适合局域网，Safari 没有对应选项只能上 TLS。
再说身份验证。Ignis 默认监听纯 HTTP 且没有登录机制，任何能访问到这个端口的人都可以读写你的整个笔记库。所以绝对不要把 Ignis 直接暴露到公网。如果需要在外网访问，务必在前面加一层认证：反向代理的 Basic Auth 是最简单的，Authelia、Authentik、OAuth2 Proxy 这类 SSO 方案更完善，也可以用 Cloudflare Access 配合 Tunnel，或者干脆走 Tailscale、WireGuard 这样的 VPN 只在私有网络里访问。官方 examples 里提供了两套完整的 Caddy 配置，分别对应 Basic Auth 和 Authelia，可以直接拿来用。路线图里提到未来会支持内置认证和多用户 OIDC，但在那之前，认证完全是自己的责任。
我个人的建议是家庭网络内用 tailscale serve 一条命令解决 HTTPS 和访问控制两个问题，既不用管证书，也天然只有自己的设备能访问，是最省心的组合。
还有一个容易踩的坑是第三方同步插件的连通性。出于防止恶意网络扫描的考虑，Ignis 服务端默认拒绝中继指向私有地址、回环地址的 HTTP 请求，所以如果你的 CouchDB 或者其他同步服务器跑在局域网或同一台 Docker 主机上，需要通过 PROXY_ALLOW_PRIVATE_HOSTS 环境变量显式放行对应的 IP 或 CIDR（注意只接受 IP 不接受主机名），或者在设置里配置 direct-fetch 让浏览器直连（这要求同步服务器开启 CORS）。走 WebSocket 的同步插件则是浏览器直连，当 Ignis 本身是 HTTPS 时，浏览器会拒绝明文的 ws:// 连接，同步服务器也需要提供 wss://，用受信任的证书或者同样套一层 tailscale serve 就能解决。
把 Electron 应用塞进浏览器不可能没有代价，有些限制需要提前知晓。最主要的是需要 Node 原生模块或 child_process 的插件无法加载，比如依赖本地执行命令的插件（典型如调用本地 Git 二进制、执行 shell 脚本的那一类）在 Ignis 里是跑不起来的，官方文档维护了一个插件兼容性页面，重度依赖某个插件的话建议先去查一下。
另一个需要留意的是密钥存储。桌面版 Obsidian 的插件可以用 Electron 的 safeStorage 借助操作系统加密敏感数据，浏览器没有等价能力，所以 Ignis 里插件存储的 API key 之类的秘密目前是明文保存的，服务端加密在计划中但尚未实现。在共享或安全性存疑的服务器上部署时，这一点要纳入考虑。
还有一些小的差异：浏览器无法弹出真正的本地文件选择器，所以像 Importer 这类插件导入文件要分两步操作，先选择文件暂存再重新执行动作；拼写检查语言跟随浏览器设置而不是应用内设置；依赖 Electron 菜单 API 的原生菜单选项被禁用。这些都属于可以接受的妥协。
最后要提醒的是，Ignis 还是一个很年轻的项目，虽然作者自己已经把它当作日常笔记工具在用，GitHub 上也已经收获了超过 1200 个 star，但处于活跃开发阶段意味着可能遇到未记录的问题。好在它只是数据的一个访问层，笔记本体始终是磁盘上的 Markdown 文件，就算 Ignis 出问题，数据本身也不会受影响，这也是我敢直接把它指向主力笔记库的原因。当然，任何时候都不要忘了备份。
Ignis 解决的是一个存在了很多年的真实痛点：Obsidian 的本地优先哲学和随时随地访问之间的矛盾。此前的答案要么是体验糟糕的远程桌面，要么是丧失编辑能力的静态发布，而 Ignis 用兼容层的思路给出了第三种答案，让你在浏览器里得到一个接近原生的、插件可用的、可编辑的 Obsidian，而数据依然完整地躺在自己服务器的文件系统里。
对我来说，它最大的价值是让 Obsidian 的访问入口从”装了客户端的设备”扩展到了”任何一个有浏览器的地方”，配合 Tailscale 之后，在公司的电脑、朋友的电脑、甚至 iPad 的浏览器里打开自己的笔记库都只是一个 URL 的事情。如果你也是 Obsidian 的自托管爱好者，手边有一台跑着 Docker 的小主机或 NAS，非常值得花十几分钟把 Ignis 跑起来体验一下。项目的 GitHub 仓库 和官方文档都写得相当清楚，部署前把安全章节读一遍，就可以放心使用了。
2026-08-11 13:00:00
2026 年山之日这个假期外面下着雨，没有出行的计划，索性看起了放到了待看列表的《卧底厨神》，因为之前看过《黑白大厨》知道了权主厨，郑主厨，本来没有对这部综艺抱有太大的期待，只是想在一个休息日放松心情看一篇轻松的综艺，但没想到完全被这三位主厨圈粉了。
看完 [[卧底厨神]]，我发现自己记住的居然不是任何一道菜，而是几个人在陌生后厨里手忙脚乱的样子。对一档美食综艺来说，这挺反常的，但我仔细想了想卧底厨神或许更适合将其归类为真人观察类综艺。
自从 [[黑白大厨]] 火了之后，美食综艺几乎被”竞技”二字绑架了：切磋、对决、淘汰、排名，厨师们像格斗选手一样被推上擂台。但卧底厨神聪明就聪明在，在这里我们看不到对决，淘汰，而是真实的餐厅后厨，真实的把每一道菜端到客人面前：三位在韩国功成名就的主厨，隐藏姓名和头衔，伪装成完全不会做菜的菜鸟，潜入意大利帕尔马、那不勒斯和中国成都的餐厅后厨，从洗碗、择菜、擦灶台、切菜做起。
他们的任务只有一个：在 5 天之内，不暴露自己厨师的身份，却要赢得当地主厨的认可，把自己的招牌菜写进餐厅菜单。
这个设定微妙在它的双重矛盾：会做菜的人要装作不会做菜，本身就是高难度表演；而装作不会的同时，又得”恰到好处”地露出潜力，否则永远轮不到你碰灶台。知道的是卧底综艺，不知道的还以为在看演技考核。
三位主厨各自带着不同的故事线。Sam Kim 是韩国意大利菜的代表人物，去了启发他料理生涯的帕尔马，伪装成转行的农夫；权圣晙顶着黑白大厨首季冠军”那不勒斯黑手党”的名号，回到了绰号的来源地那不勒斯；[[郑智善]] 作为韩国首位女性中餐主厨，伪装成拳击手、去了川菜的大本营成都。这三位主厨的人物刻画，每一个都非常生动。我们可以从节目组叙事的娓娓道来中去熟悉每一个主厨的人物生平。
权圣晙主厨是傲娇的，有点拽，但拽得很可爱。日常生活里不拘小节，演播室里主持人问”想改变第一天的什么内容”，权主厨的回答是想改一下后采时的发型，此时再去看权主厨的头发时，我当场笑死。但反差也恰恰在这里：日常呆萌又安静的一个人，一进厨房，那种属于厨师的专注立刻就出来了。
郑智善主厨的反差则在演播室和后厨之间。演播室里的她是强势果断的领导者气质——毕竟是拥有多家餐厅的女老板；但在成都当菜鸟的时候，你能看到她细腻的一面：观察力很强，会照顾周围人的情绪，外刚内柔。她对自己的要求也高到近乎苛刻：厨房里大家都坐着休息，但从来没看到郑主厨坐下过，她不允许自己的餐厅里听歌。从她的自述里也能感受到一路走来的艰辛——作为一名女性主厨，长期得不到行业内的认可，但她依然靠着实力、经验和努力获得了今天的成就。也正因为这样，当她在成都被地道川菜和沉得多的中式炒锅接连挫败、肉眼可见地陷入自我怀疑时（据 PD 事后采访说，制作组当时甚至担心第二天还能不能拍下去），这条线才格外有张力。后面怎么走，就不剧透了，留给你自己看。
而我最喜欢的，是节目中出现的第一位主厨 Sam Kim（샘킴）的故事。明明已经是多家餐厅的大老板，管理着 20 多名员工，但到了异国他乡，依然是那个胆小、内向、不会主动开口说话的人。性格温和，但专业能力藏不住。经典的搞笑段落也大多是他贡献的——意大利饺子的形状连着做错了 3 次。虽然犯了这么多新人的错，但依然能看到 Sam Kim 主厨的认真，上班前学好意大利语，背下来再上班，看他这条线的时候，最容易让我想起初入社会的菜鸟。这样一位温柔害羞的大叔，谁能不喜欢。
导演 [[洪镇珠]] 在采访里说过一句我很认同的话：这个节目从来不是料理综艺，更接近一部”人类纪录片”。节目组没有为了效果放水，餐厅也没有配合演出——于是镜头里留下的是货真价实的挫败、鸡同鸭讲的语言障碍、深夜才结束的营业，以及在这一切之上依然生长出来的感情。正因为这 5 天的关系不是演出来的，后面每一个情绪节点才都立得住。
观众也用遥控器投了票：播出期间收视率一路涨到 6.2%，是首播的 3 倍，连续 10 周同时段第一。大家早就看腻了被剧本保护起来的成功。
另一个值得说的点是”重走来时路”这个母题。三位主厨都不是空降的天才，都当过厨房最底层的小工。节目让他们在职业生涯的顶点重新体验一次底层——Sam Kim 每天早上背意大利语，琢磨怎么跟前辈搭话；权圣晙营业到半夜也一声不吭地干活。这种东西，综艺剧本写不出来。
好节目不是偶然。写这篇观后感的时候，我顺手翻了 [[洪镇珠]] PD 和尹阿尔音编剧的收官采访，几个幕后细节很值得记下来。
企划始于 2025 年末制作团队构思新节目的阶段。洪镇珠是入行 11 年的 PD，此前一直做 [[帐篷外是欧洲]] 系列，这是其第一次从零企划一档新节目。出发点是一个判断：观众的眼光越来越高，必须做”真的”才能让人满足；而且要做一档能让人”过度沉浸”的节目——这种沉浸不只属于观众，也属于出演者。用洪镇珠的话说，出演者要沉浸到忘记自己在拍摄，才会讲出真正的故事。卧底潜入的设定就是从这个想法里长出来的。
真正难的是落地。给主厨们编的掩护故事是”拍摄一部隐退名人挑战第二人生的纪录片”；而选餐厅要同时考虑味道、员工的性格倾向、顾客构成、厨房的运作体系，制作组形容那个阶段是”跑断腿、磨破嘴”。餐厅方面起初并不友好——陌生人跑来说要拍摄，换谁都会起疑，成都餐厅的家人和帕尔马餐厅都疑虑重重，信任是一家一家磨出来的。
选角的标准也有意思：最看重的不是名气，而是”对这个节目有多大兴趣”。制作组在企划初期从隐世高手到新人厨师广泛请教，最终选中的三位，都是对企划本身充满好奇、并且能把当年做厨房小辈的经历讲得生动有趣的人。事后看，这个标准选出来的人确实撑起了节目——对企划没有热情的人，很难心甘情愿地在异国后厨打 5 天零工。
编剧尹阿尔音的说法则从另一个角度印证了节目的定位：从一开始就没把它当料理节目做，关注的是主厨们的工作方式，以及在升级过程中与当地员工建立的关系。所以那种”人类纪录片”的质感不是剪出来的，是策划阶段就定下来的。
看 [[黑白大厨]] 的时候，作为观众我只是一味地觉得比赛、竞技精彩；但在这档综艺里，虽然讲的是厨神们如何从底层做起，却无比”真实”。语言不通、反复犯错、在厨房里不知所措——这些画面更让我想起自己初入社会时的情形：看眼色，讲人情，还会在一些重要的时刻犯错。但身边的所有人都非常友好、善良，可以包容菜鸟的犯错；也可以看到当他们被主厨认可之后的那种成就感。
我想，这三位主厨以他们在韩国的位置，本可能不会参加这么辛苦的节目——因为我们在节目里是能看到那份辛苦的。从他们自己的回忆中，也可以感受到过去为了学习料理付出的汗水。但我恰恰是被这些真实存在的人感动了。短短几天时间内建立起来的情感，综艺中所表现出来的辛酸与情义，以至于让我都忘记了他们最终的目标，更愿意去看他们和这群普通人最后的结局。
如果你被上面的描述勾起了兴趣，几个实用信息：
卧底厨神给我的最大启发其实跟做菜无关：一个领域的顶尖高手，把头衔摘掉之后还剩下什么？节目给出的答案是——剩下的是习惯。是每天提前到岗的习惯，是一遍一遍反复擦拭的灶台，是被否定之后第二天照样出现的习惯。头衔证明不了这些，只有把人扔回底层才能看见。
至于三个人最后到底有没有把菜写进菜单，这里就不说了。反正看到后来，连我自己都忘了这档节目原本的任务是什么——能让观众忘掉规则、只记得人的综艺，不多见。期待衍生篇。
2026-08-04 13:00:00
今天在终端里跑 mise upgrade 想要升级 herdr 的时候，突然看到一条以前没见过的 WARN 提示，「mise WARN 1 newer herdr release hidden by minimum_release_age」，大意是有一个更新的版本存在，但因为发布时间太短，被 minimum_release_age 设置过滤掉了，暂时不会被安装。最后去看了 [[mise]] 的更新日志才发现，这是 mise 在 2026 年新引入的一个供应链安全机制，而且从 v2026.6.2 开始默认对所有人生效。这篇文章就把这个机制的来龙去脉、警告的含义以及怎么配置讲清楚。
简单说，minimum_release_age 的作用是：一个新版本发布之后，必须先等待一段时间（默认 24 小时），mise 才会认为它”可用”。在这个时间窗口内，即使上游已经发布了新版本，mise install、mise upgrade、mise latest 这些命令也会当它不存在，继续解析到上一个满足时间要求的版本。
这个设计针对的是近几年愈演愈烈的软件供应链攻击。典型的攻击场景是这样的：攻击者拿到某个流行包的发布权限（钓鱼拿到 maintainer 的 npm token、CI 配置泄露等等），发布一个带恶意代码的新版本，然后等着全世界的自动更新工具在几小时内把它拉下来。这类被投毒的版本通常存活时间很短，社区、安全厂商和 registry 官方往往在几小时到一两天内就会发现并下架。所以”等一等”本身就是一种非常朴素但有效的防御——只要你不做第一批吃螃蟹的人，绝大多数投毒版本在到达你机器之前就已经被清理掉了。
这个思路并不是 mise 首创。[[Renovate]] 很早就有 minimumReleaseAge 配置，用来推迟自动升级 PR 的创建；[[pnpm]] 也在 10.16 之后加入了同名的 minimumReleaseAge 设置，安装依赖时跳过太新的版本。mise 做的事情是把同样的理念搬到了开发工具版本管理这一层——你通过 mise 安装的 node、go、terraform，以及各种通过 aqua、npm、pipx 后端装的 CLI 工具，统一套上这道时间闸门。
回到开头那条警告。当你运行 mise upgrade 或者 mise outdated 之类的命令时，mise 会去查询各个工具的远程版本列表。如果它发现存在比当前已安装版本更新的版本，但那个版本的发布时间还没超过 minimum_release_age 设定的时长，就会打印一条 WARN，告诉你有 N 个更新版本因为太新而被暂时过滤掉了。
这里要强调的是，这不是错误，也不需要你做任何事。mise 会继续使用满足时间要求的最新版本，被过滤的那个版本会在时间窗口过去之后（默认发布满 24 小时）自动变为可用，下次再跑 mise upgrade 就会正常升级上去。这条警告存在的意义只是告知，避免你困惑”明明上游发新版了为什么 mise 装不到”。
从 v2026.6.2 开始，mise 为所有能提供发布时间戳的后端内置了这个 24 小时的默认延迟，包括 core（node、go 这些核心工具）、aqua、github、cargo、go、npm、pipx 等。也就是说即使你从来没在配置里写过 minimum_release_age，这个机制也已经在保护你了，这也是为什么很多人像我一样是先看到警告、再反过来查文档的。
在翻 mise 文档和源码的过程中，我发现这个机制有几个行为细节值得单独说清楚，不然很容易产生错误的预期。
第一，它只影响模糊版本解析，不影响显式 pin 的版本。所谓模糊版本，就是 latest、node@20、terraform@1 这种需要 mise 去解析”到底是哪个具体版本”的写法。如果你在 mise.toml 里明确写死了 node = "22.14.0"，那不管这个版本是不是一小时前刚发布的，mise 都会照装不误。这个设计是合理的——显式 pin 意味着你明确知道自己要什么，工具不应该替你做主；而模糊解析场景下你把选择权交给了 mise，它就有责任帮你过滤掉风险窗口内的版本。
第二，过滤能力取决于后端能不能提供发布时间戳。core、aqua、github、cargo、go、npm、pipx 这些后端能拿到每个版本的发布时间，过滤就能生效；拿不到时间戳的版本会被默认放行，不会因为”无法判断”而被误伤。
第三，传递依赖的覆盖范围目前还有限。对于 npm: 和 pipx: 后端安装的工具，mise 会把时间窗口透传给底层的包管理器，让传递依赖也遵守同样的规则；其他后端目前只过滤顶层工具本身的版本。如果你的威胁模型主要担心 npm 生态的依赖投毒，这一点算是个不小的加分项。
默认的 24 小时对大多数人来说是个不错的平衡点，但 mise 提供了完整的配置手段，可以按自己的风险偏好调整。
全局调整时间窗口，在 ~/.config/mise/config.toml 或项目的 mise.toml 里设置：
[settings]
minimum_release_age = "7d" # 只安装发布超过 7 天的版本
时长支持 24h、7d、1y 这种相对写法。如果你所在的团队对安全要求比较高，把这个值调到 3 到 7 天是常见做法。
有些工具的更新是时间敏感的，比如漏洞扫描器 trivy，它的新版本往往携带最新的漏洞库，晚装一天反而降低安全性。这种情况可以按工具覆盖全局设置：
[settings]
minimum_release_age = "7d"
[tools.trivy]
version = "latest"
minimum_release_age = "1d"
也可以用排除列表把特定工具或整个后端排除在全局策略之外，支持通配符：
[settings]
minimum_release_age = "7d"
minimum_release_age_excludes = ["trivy", "npm:*"]
需要注意优先级顺序：命令行的 --minimum-release-age 参数最高，其次是按工具的设置，最后才是全局设置。被排除的工具仍然会尊重它自己的 per-tool 设置和命令行参数。
如果某次你确实需要立刻装上一个刚发布的版本（比如上游刚修了一个影响你的 bug），不用改配置文件，临时用命令行参数绕过即可：
mise upgrade node --minimum-release-age 0
mise latest node --minimum-release-age 2024-01-01 # 也支持绝对日期
反过来，如果你完全不想要这个机制，在全局配置里把 minimum_release_age 设为 0 就可以彻底关掉。不过在关掉之前建议想清楚，这个默认值的存在几乎没有日常成本——你感知到的无非就是新版本晚一天到手——换来的却是躲开绝大多数投毒版本存活窗口的保护。
另外值得一提的是它和 mise.lock 的配合。lockfile 保证的是”团队所有人装到的是同一个被验证过的版本”，minimum_release_age 保证的是”解析新版本时不会撞上刚出炉的风险版本”，两者是互补关系而不是替代关系。对于有 CI 环境的项目，lockfile 加上默认的时间窗口，基本就把工具链这一层的供应链风险控制在了一个比较舒服的水平。
minimum_release_age 是那种典型的”好的默认值”设计：机制本身极其简单，就是给新版本加一道冷静期，但它选择了默认开启，让所有 mise 用户在无感知的情况下获得了对供应链投毒攻击的基础免疫。从 npm 的 event-stream 到近几年层出不穷的 maintainer 账号劫持事件，这类攻击的共同特点就是投毒版本存活时间短、传播依赖自动更新，而”等 24 小时”恰好精准打在这两个特点上。
