MCP | Francis Du

wcode 是怎么从一个 MCP Bridge 变成现在这样的

Sat, 12 Sep 2026 05:40:00 +0800

GitHub ↗文档 ↗

我做 wcode 的起点，其实不是想再做一个 Coding Agent。

最开始的想法很简单：把网页里已经能直接用的模型拿来写代码，同时让它们能读到我电脑上的真实仓库。模型在浏览器里，代码却在本地。稍微复杂一点的问题，我就得复制文件、上传压缩包、解释目录结构；代码一改，前面传进去的内容马上又旧了。

所以第一版 wcode 更像一座桥。它把本地仓库通过工具接给网页端模型，让模型可以自己搜索文件、读代码、做修改、跑检查。后来 MCP 出现，这件事有了更标准的连接方式，但真正让我继续往下做的，并不是“终于能连上了”。

连接打通以后，另一个问题反而越来越明显：Agent 到底是怎么读代码的？

不少 Code CLI 在仓库发现阶段会大量使用 grep、ripgrep、文件列表和各种 shell 命令。这个做法本身没问题，我自己也一直在用。它很快，找一个字符串、文件名或者明显的符号时甚至就是最合适的办法。

问题在下一步。

搜索返回的是“这里命中了几段文本”。模型还得自己从这些片段里重新拼出：哪个才是真正的定义、两个同名符号是不是一回事、谁在调用谁、改这一处会波及哪里、对应测试在哪、某条关系到底只是文本上看起来像，还是语言服务器真的确认过。

模型越强，这种做法当然越能工作，但本质上还是把大量仓库理解工作重新丢回了 Context Window。仓库一大、同名符号一多、跨模块调用一复杂，误判就很容易从这里开始。

wcode 后来就是从这里开始变的。我不再只加命令，而是开始单独处理“模型怎么读一个仓库”这件事。

后来我开始管 Agent 怎么读仓库#

现在的 wcode 仍然会用文本搜索，而且普通定位默认就应该走便宜的路径。问“FooConfig 在哪”，没必要为了显得高级就启动一整套语义分析。

但问题一旦变成“谁调用它”“这个实现有哪些引用”“改这里会影响什么”“哪个测试真正覆盖这条行为”，纯文本命中就不够了。wcode 会先用 Tree-sitter 建立稳定的语法结构，需要跨文件语义关系时再使用可用的 Warm LSP；同时把 Git 当前状态、Design State、测试入口和已经知道的软件图关系一起带进来。

最后交给模型的，不只是几段搜出来的源码，而是一份有边界的任务上下文：相关符号和精确范围、引用或调用关系、关联测试、当前修改、项目约束，以及这些信息来自哪里、是什么精度、对应哪个版本。

可以把两种读取方式粗略理解成：

常见文本发现链路：任务 → grep/ripgrep / 文件切片 → 命中文本 → 模型自己重建代码关系。
wcode 的链路：任务 → 便宜定位 → 按需解析语法/语义关系 → 整理成任务上下文 → 模型基于带来源和精度的证据继续推理。

wcode 不是为了淘汰 grep。精确定位时搜索通常就是正确工具；需要结构、调用、实现、影响或验证关系时，再增加更强的代码理解。

拿一个很普通的例子：给列表接口增加“按状态筛选”。只搜接口名，很容易找到 Handler，却未必会顺着参数定义、查询构造、调用方和测试一路看完。agent_context 会先围绕当前任务整理相关实现、测试、项目约定和可用的检查入口；如果任务明确需要 Caller、Reference、Implementation 或 Impact，Readiness 再提示 Agent 使用语义导航。

这点对我很重要：不是每个问题都做最重的分析，而是让模型知道什么时候搜索已经够了，什么时候必须继续确认代码关系。 工具能证明到哪一层，就只说到哪一层。Tree-sitter 的语法事实不会包装成编译器语义；LSP 不可用时也不会假装已经找全了调用方。

接上仓库以后，还得防止改错#

继续拿筛选接口这个例子。Agent 读完文件，正在生成修改时，我也可能在编辑同一个文件。

如果它直接把旧版本上的修改写回来，就可能覆盖我刚加的内容。所以 wcode 读文件时会返回一个 SHA，可以把它理解成文件内容的指纹。编辑时必须带上这个指纹；内容已经变了，旧编辑就会被拒绝，Agent 要重新读。

修改也需要控制范围。读几个互不相关的文件可以一起做；两次修改都要动同一个文件，就不能随便同时写。改完之后，用 review_changes 看实际差异，再用 verify_project 跑项目里已有的检查。

我希望一次任务最后能回答：改了哪里，检查过什么，还有什么没确认。

wcode 文档里把这一层叫作“工程控制面”。落到日常使用，就是把文件、操作记录和检查结果留清楚。换一个模型或者接着做下一轮，也能查到前面发生过什么。

测试通过，也得看是哪一次修改#

给接口加了筛选条件，测试通过了。接着又调整参数解析，却没有再跑测试。这时，前面的通过记录只能说明前一个版本通过了。

wcode 会把检查结果和当时的代码、设计版本关联起来。界面里的几个状态也有区别：找到测试文件，只能算“有对应检查”；真正运行过、结果通过、结果仍适用于当前版本，是后面的几件事。

检查本身也要选对。这个博客用 Hugo 生成网页，写完 Markdown 以后，至少要真正构建一次，确认中英文页面都生成了、图片能找到、原来的地址没有变。只看文字没有语法错误，证明不了这些事情。

对代码项目，则需要运行相应的编译、测试或其他项目检查。涉及更大风险的改动，可以按配置增加更深入的验证。下图列出了这些通道，并不是每次修改都要把它们全部跑一遍。

项目和验证计划决定哪些检查必须完成；缺少执行结果，不能靠一句“应该没问题”补上。

历史上的成功修改可以帮助下一次任务找方向，但旧测试结果不能一直沿用。这是我希望 wcode 替我记住的一件事。

项目里的规矩，得有地方放#

有些要求从一段代码里看不出来。

比如这个博客，中文页面一直在根路径，英文放在 /en/；摄影 Gallery 有自己的页面和脚本；改文章时要保留原来的公开地址。Agent 如果不知道这些约定，很容易在完成眼前任务时，顺手改掉别的行为。

wcode 可以把这类要求写进仓库的 .wcode/ 目录。文档把它们称为 Design State，里面记录需求、组件、约束和验收条件。之后查项目、分析一次修改的影响时，可以把这些要求一起带出来。

工程观测台默认打开架构页面。从这里可以看组件对应哪些源码、关联哪些需求，以及分析工具发现了哪些依赖。

这些记录需要跟着项目维护。图画出来了，不代表架构就没有问题；它的用处是让原来散在文件和讨论里的信息，有一个可以一起核对的地方。

它能访问什么，由谁决定#

wcode 围绕选定的 Workspace 工作，也就是这次允许访问的项目范围。文件操作会检查路径、受保护位置和不安全的链接，已有文件的修改还要检查内容指纹。

命令另有规则。常见、有明确边界的开发命令可以直接运行；需要额外信任的操作，会进入本地授权流程。访问页面可以查看具体请求，由操作者决定是否允许。更宽的会话授权或 Full Access，也需要操作者明确选择。

能连接到 wcode，不等于可以执行任意命令或访问任意文件。

本地客户端可以用 stdio 启动 wcode；远程客户端通过 OAuth 连接运行中的服务。这两种接法提供同一套仓库能力。文件操作发生在仓库所在机器，使用云端模型时，读出的代码仍会作为工具结果交给对应客户端。

wcode 的这些检查属于工具和仓库层，并不等同于操作系统沙箱。

界面里能看到什么#

我主要用界面确认工作进行到哪里。

终端面板能看到连接、当前项目、任务和授权请求。按 W 打开工程观测台，按 O 打开设置页面。观测台里可以看架构、当前修改、需求和项目文件，也可以查看前面提到的验证记录。

任务慢下来时，任务活动页面会更有用。它把排队时间和实际执行时间分开，也显示子进程和资源使用情况。一个命令迟迟没结束，可能是在等运行机会，也可能是真的执行了很久，处理办法不一样。

wcode 也分别限制 CPU 工作、文件读写和子进程的并发量。互不依赖的事情可以一起做，机器也要留有余量。这部分仍然需要结合实际任务观察，不能只看一个并发数字。

怎么开始用#

如果你已经有习惯使用的 AI 编程助手，可以拿一个自己熟悉的项目试试。先做一个小修改，比较容易判断工具找的代码对不对、修改有没有跑偏。

macOS 和 Linux 可以用发布版安装脚本：

curl -fsSL https://raw.githubusercontent.com/francis-du/wcode/main/install.sh | sh

Windows 的安装方法见快速开始。装好后，在项目目录里运行：

wcode setup

按提示选择全局或当前项目配置，再重新连接 Agent。本地 stdio 模式由客户端启动进程；需要终端面板、网页界面或远程接入时，运行 wcode。远程接入使用程序显示的当前 MCP 地址，并完成 OAuth，详细步骤见客户端集成文档。

第一轮不用把所有功能都配置好。先跑一个最小闭环：

让 Agent 找到一处实现；
改一个行为；
跑对应检查；
自己看一遍 diff。

接下来再把确实需要反复遵守的项目约定写进 .wcode/。

源码在 GitHub，安装和接入说明放在项目文档里。模型仍然由你正在使用的服务提供，wcode 负责连接和处理仓库这一侧的工作。

wcode v0.6.2：我不再拿 SLOTS 当性能了

Sat, 12 Sep 2026 05:32:00 +0800

前几天我一直盯着 wcode 的并发面板看。

SLOTS 32，PEAK 看起来也不低，但实际跑起来还是有一种很奇怪的感觉：数字挺忙，任务不一定真快。

我把执行链拆开看了一遍，问题就清楚了。

外层 Tool Slot 只表示请求已经准入。CPU、文件 I/O、cargo、git、Language Server 还有各自的线程池或队列，外面 32 个槽位全亮，并不代表里面 32 份工作都在向前跑。

0.6.2 先把这些资源分开计量和限制。

SLOTS、CPU、I/O、子进程是四件事#

现在我更愿意把执行路径看成：

Tool admission
      ↓
Foreground CPU budget
      ↓
Bounded file I/O pool
      ↓
Child process / Git probe queues

它们有不同的瓶颈。

前台 CPU 工作线程会取硬件并行度、8 个线程、内存推导上限和请求并行度的最小值。阻塞线程池上限提高到 64，是为了不让大量独立阻塞请求被隐藏的较小线程上限卡住。

独立文件修改走共享、有界的 I/O Pool；固定形式的 Git 状态和差异检查走独立 Probe Queue，不再和重型编译器进程抢同一组名额。

默认资源预算下，重型子进程仍然是很小的并发数。因为同时启动 20 个 cargo 不会 magically 变快，只会把机器打爆。

我专门撤回过一个“看起来更并行”的优化#

这轮有一件事我觉得挺重要：我试过把热读取也放进更宽的线程池，结果本地配对实验更慢。

所以撤回了。

做 Agent Runtime 很容易有一种冲动：

线程更多 = 更快
队列更深 = 吞吐更高
并发数更大 = Agent 更强

配对结果不好看就撤回。0.6.2 后面的资源调整也基本按这个标准做：先把不同类型的工作隔开，别靠调大一个统一并发值解决所有问题。

32 个命令排队时，我还希望 Read 能进去#

如果所有 Tool Slot 都被执行进程占满，Agent 连 read_file、状态查询这种轻操作都进不来，系统就会出现另一种死锁感。

所以执行进程类工具在拿总 Tool Slot 前，还要先拿一层 Execution Admission。

总量是 32 时，执行类请求最多占 28 个槽位，给非执行工具留四个受控余量。单槽位配置则保留一个可用名额，不会把自己完全饿死。

它不保证固定延迟，但编译队列再长，read_file 和状态查询至少还有机会进来。

明确的错误位置，不应该先全仓搜索#

性能不只在 Scheduler。

我调真实任务时发现另一个很浪费的路径：模型已经拿到了这种信息：

error[E0308] at src/runtime/harness/context_budget.rs:33:9

结果 agent_context 还先做一遍广域符号检索，再回来读这个明确位置。

这顺序反了。

现在带文件和行号的诊断会先经过 Workspace 保护解析，然后直接保留对应源码原文、行范围和 SHA 编辑前置条件。简单位置查询可以暂缓 Repo Graph 扩展；调用方、Impact、架构或显式 Scope 查询仍然走深入路径。

缺失位置也不会先把一堆无关文件索引起来再告诉我“没找到”。

这类任务现在先吃掉已有的精确位置，只有问题真的需要跨文件关系时才继续扩图。

同一个冷索引也不应该被重复建 10 次#

并发 Agent 很容易同时问同一个文件。

以前多个冷查询可能一起发现“没有索引”，然后各自开始建。

现在同一 Workspace、同一文件的冷查询会共享正在进行的索引构建。不同文件仍然可以独立执行；失效和版本变化会阻止旧构建结果晚到后重新污染缓存。

这里没有做增量 Tree-sitter，也没有引入全仓快照，只是把同一份冷索引的重复构建合掉。

`symbol_context` 开始对自己返回的版本负责#

另一个一致性问题是：索引说 Symbol 在 A，但真正读正文时文件已经变了。

如果这时还把旧签名和新正文拼成一个结果，Agent 会拿到一个内部自相矛盾的 Context。

现在 symbol_context 会核对符号信息和正文是不是同一文件版本。发现旧索引最多重新获取一次；文件持续变化、拿不到稳定版本时，就明确失败。

我宁愿返回“现在无法稳定读取”，也不想返回一个看起来完整的 Frankenstein Context。

验证计划不能静默只跑前八项#

0.6.2 还修了一个更严重的问题。

混合语言仓库里，完整验证可能推导出十几项检查。旧路径有一处会静默只取前八项。

这类优化最危险的地方不是少跑了几个命令，而是上层可能还把已经执行的前缀描述成“完整验证”。

现在先构造完整计划，整体上限是 32。超限就在派发前失败，明确告诉调用者没有执行检查，而不是偷偷截断。

验证历史也会在一次请求里共享代码 Revision 和 Evidence Snapshot，减少重复扫描；结果要同时匹配 Code 和 Design State 才能展示为当前有效。

窄范围检查不能把宽范围失败抹掉，时间戳冲突按失败关闭。Evidence 缺失或扫描截断，也不能被解释成通过。

`verify_project` 可以断线以后再查#

项目验证现在还复用了 MCP Tasks 扩展。

客户端支持 Tasks 时，服务端可以先持久化任务并返回 taskId，验证继续由 Runtime 管理。客户端断线后，可以拿同一个 ID 查询状态。

这里我刻意没有加一个模型可见的 async=true 参数，也没有把断线等同于自动重试。

因为对带副作用的系统来说，最危险的一句话就是：

没收到响应，那再执行一遍吧。

完成状态只表示底层工具返回了结果，不等于检查通过；调用者还必须读真正的 passed / error 状态。

配置终于开始收敛#

wcode 可调参数越来越多以后，另一个问题也很明显：高级参数是给调试和特殊机器用的，不应该逼所有人启动时手写一排数字。

所以现在有三档常用性能配置：

balanced
fast
light

也可以先预览：

wcode setup --performance fast --dry-run
wcode --show-config

真的执行 Setup 才会保存审核过的启动选项。

同时新增了：

wcode help-all
wcode help-all setup
wcode help-all --json

它直接从真实 CLI Parser 生成完整命令和参数目录，包括隐藏高级选项、短参数、别名、默认值和枚举值。

普通 --help 继续保持短。我不想为了“可发现性”把日常帮助页重新塞成说明书。

WebUI 首屏也一起收了#

Observatory 这轮主要改首屏信息层级。

现在执行活动、待批准请求、工作树变更、当前有效验证结果分开显示。Architecture 入口改成可搜索组件卡片和详情 Inspector，Design / Implementation / Overlay 图仍然保留，但不再要求用户先读一张很大的图才能知道项目现在发生了什么。

活动刷新也和慢项目刷新拆开。页面隐藏时停止轮询；共享进程资源和当前项目任务分开标记；“没有采样”不再画成“0”。

我主要想避免一件事：没有数据时别画成一个看起来很健康的数字。

做完以后，我给自己留了几条检查项#

我最后给自己留下几条明确的检查项：

Slot 数不等于吞吐；
拿到文件和行号，先读明确位置；
Verification mapped 和 executed 分开；
Task completed 和 checks passed 分开；
断线不自动重放；
没有采样就显示 unknown。

0.6.2 没有一个单独的大功能，更多是在把这些边界钉死。对我来说，这比再加一批 Tool 更实际。

wcode v0.6.1：`parallel_tools` 不再按层等

Sat, 12 Sep 2026 05:31:00 +0800

v0.6 开始在 agent_context 里标出可以并行的工作。接着我去看 Runtime 本身，发现 parallel_tools 虽然已经有依赖图，执行时还保留着按层推进的做法。

例如：

A ─→ C

B ─────────→ D

假设 A 100ms 完成，B 要 5s，C 只依赖 A。

按“层”执行时，很容易变成：

第一层：A + B
        ↓ 等两者都结束
第二层：C + D

C 明明在 100ms 时已经 Ready，却因为一个和自己无关的 B，被迫多等几秒。

所以 v0.6.1 我把调度器改成了 completion-driven。

Ready 的任务不应该等同层慢分支#

现在 Scheduler 只看一个问题：

这个任务自己的前置依赖是不是已经完成？

满足就进入 Ready Queue。

实际任务图通常不整齐。一个慢测试、一个大文件读取、一个外部命令，不该顺手把无关分支也拖住。

失败也只应该污染依赖它的分支#

同样的原则也用在失败上。

如果：

A → C
B → D

A 失败，那么 C 应该被 Skip，因为它的前置不成立；但 B 和 D 不应该跟着一起失败。

所以运行时会区分依赖失败导致的 Skip、当前任务自己的运行失败，以及完全独立、仍然可以继续的分支。

这对批量读取、搜索、验证尤其重要。Agent 不应该因为一个不存在的可选文件，就失去其他已经能确定的结果。

Partial 不能假装 Complete#

这轮我把批处理结果的语义也重新收紧了。

批量读、创建、编辑、移动会明确报告：

complete
partial
failed

并保留逐项结果。

如果一个批次只完成了一部分，MCP Result 会保守地带错误标记，依赖整个批次的后续任务不能把它当作完整输入。独立分支仍然继续。

重试也不应该重放整个批次。先核对状态，只重试失败项。这对写操作尤其重要，因为“请求失败”不等于“所有副作用都没发生”。

并行写入最怕错误合并#

为了减少 Tool Call，wcode 会在安全条件满足时合并部分文件编辑。

这里我宁愿少合并一点。

同一个文件、同一个 SHA 的 Edit，如果中间隔着一个依赖 Read、Move 或其他会改变语义的操作，就不能跨过去合并。否则 Scheduler 会把原本有先后关系的工作偷偷变成一个事务。

合并前也会检查既有的 128 项编辑上限，不能因为优化路径就绕过原来的安全边界。

如果一次优化改掉了原本的先后关系，那就已经不是调度优化了。

Cancel 也必须真的往下传#

异步系统里还有一个很烦的问题：外层任务取消了，不代表里面已经排队的工作自动消失。

如果父请求断开，而子任务还在队列里，最糟的情况是用户以为“已经取消”，几秒后某个写操作才突然开始。

v0.6.1 把取消传播继续往下压：父任务取消会取消仍在排队的子任务；持久 MCP Task 被取消或 TTL 过期，也会取消它拥有的执行任务。

已经开始的阻塞文件操作不会假装回滚。这条边界也要说清楚。

并发许可要跟真实工作走#

以前还有一种容易让面板数据看起来比实际更漂亮的情况：外层 Future 被取消以后，如果并发许可提前释放，但底层阻塞工作其实还在跑，就会出现“系统看起来有空位，实际上旧工作没结束”。

现在已经启动的阻塞工作会继续持有对应许可，直到结束或异常退出。排队工作取消则会释放预留。

我更愿意让数字难看一点，也不想让 Scheduler 对自己的真实资源状态撒谎。

Context 也继续往目标优先收紧#

顺手还改了一轮 agent_context 的候选排序：精确定义优先于相似辅助函数；直接目标文件优先于按字母排在前面的 Design 映射；并行建议开始结合当前 Scope、活动 Worklist Lane 和运行时并发上限，而不是固定最多四路。

Lane 数只用来给 Agent 提示，并不能证明两件事真的独立。最后仍然由真实资源和依赖决定能不能一起跑。

Observatory 不再把“有映射”当“已验证”#

Project Observatory 这轮还修了一个我很在意的表达问题。

以前“某个 Requirement 有 Verification 映射”和“这个 Revision 上真的执行并通过了验证”在视觉上太容易靠近。

现在会明确区分：

verification mapped
executed
passed
fresh proof

因为有测试文件，不等于测试跑过；测试跑过，也不等于它属于现在这份代码。

这版主要把无意义等待拿掉#

v0.6.1 基本都在修执行语义：Ready 就进队列，失败只截断依赖分支，Partial 明确报告 Partial，Cancel 继续往子任务传，许可跟着真实工作释放。

它不会把本来串行的任务凭空变快，但长任务里少掉几次无关等待，体感很明显。

再往后到 v0.6.2，我又继续拆了一个误区：外层 SLOTS 很高，不代表真实吞吐就高。

wcode v0.6：哪些工具调用可以一起跑

Sat, 12 Sep 2026 05:30:00 +0800

v0.5 做完 Warm LSP Runtime 以后，我原本打算继续补 Semantic。

实际拿 wcode 连续写了几轮代码，先暴露出来的却是执行节奏：模型已经知道几件事互不依赖，还是经常按顺序一个个调用工具。

例如一个普通修改，前面经常同时存在几条工作：

读目标文件
查相关测试
看项目约束
确认调用方
检查工作树

这些动作很多没有依赖关系。如果 Prompt 只写一句“可以并行”，模型仍然很容易串着做。

v0.6 就从这里开始改。我想让 Harness 少给模型一层猜测：当前任务有哪些入口，哪些可以一起做，哪些必须等前一步完成。

`agent_context` 不再只是一包上下文#

最早的 agent_context 主要解决 Context 成本。

它把 Design State、Repo Map、目标源码、SHA、验证入口和项目约束压进一个有界包里，让模型不用每次从根目录重新理解一遍。

到了 v0.6，我给这份 Context 又加了一层执行信息：

你现在应该做什么？
哪些动作可以一起做？
哪些动作有真实依赖？
哪些文件已经是可编辑目标？
哪些 Semantic Provider 已经可用？
这次修改应该控制在多大范围？

所以 Context 里开始明确带 Minimal-change Strategy、Complexity Budget、Active Worklist、Hot Source、Semantic Provider Readiness、绑定当前 Revision 的文件 SHA、候选 Dependency Lane，以及推荐并发数和立即并行的执行指引。

现在这份 Context 除了描述仓库，也会把这次任务已经确定的执行入口一起带出来。

Parallel-first 不等于“把槽位占满”#

并行最容易做成一个漂亮但没什么用的数字。多发几个 Tool Call 很简单，麻烦的是先确认它们之间到底有没有依赖：

独立 Discovery     ─┐
独立 Read          ─┼─→ 同时开始
独立 Review        ─┤
独立 Check         ─┘

需要前置结果的 Edit ───→ 等依赖满足再开始
同一文件冲突写入     ───→ 串行
授权后才能执行的命令 ───→ 等批准

v0.6 的规则很直接：先看依赖，再决定哪些调用一起发。

v0.6 的 Skill 和 Agent 工作流也开始明确要求：Host 支持并行调用时，应该尽早把独立的 Discovery、Read、Review、Check，以及不重叠 Edit 发出去。

我不想让模型自己猜仓库结构#

以前 Agent 虽然拿到了很多能力，但仍然可能自己脑补：

这个项目大概是 Rust + Web？
这个目录看起来可能是 UI？
这里应该跑 cargo test？
那个 Language Server 应该已经能用了？

这种猜测单次看没什么，长任务里会不断累积。

所以 Task-ready Context 会更主动地把已经确定的东西摆出来。目标文件是谁，就把目标文件和 SHA 放前面；当前 Scope 是什么，就把相关源码和 Worklist Lane 放前面；Semantic Provider 还没准备好，就明确说没准备好。

我在 Software Graph 那篇里写过一次：Tree-sitter、LSP、Runtime 是不同精度的事实。

执行层也照这个规则。Provider 没准备好就明确标出来，不用一个模糊状态让模型自己猜。

LSP 也开始按真实安全边界工作#

v0.5 把 LSP 做成了 Warm Semantic Runtime。

v0.6 又补了一层：Server Discovery、Binary Identity、Bounded Warm Session、Source Revision Sync 和 Safety Profile。

Language Server 不是纯文本查询器。它可能读取项目配置、调用构建系统、加载插件，甚至间接触发仓库里的代码。

所以“机器上装了 rust-analyzer”不等于“Agent 可以无条件启动 rust-analyzer”。如果某个 Server 没有明确的 Automatic Safety Profile，wcode 会 Fail Closed，然后进入精确授权流程。

命令授权从“允许/禁止”变成精确指纹#

v0.6 还有一块变化，我自己用起来很明显：本地探查命令少打断了，但真正可能执行仓库代码或者产生副作用的命令，也不再只有“永久拒绝”这一条路。

只要没有撞上硬安全边界，就可以生成一次精确的 RiskyExecution 请求。

批准绑定的是：

Workspace
Program
Arguments
Working Directory

我批准一次 cargo test --locked，不代表顺便批准 cargo publish，更不代表给 Agent 无限 Full Access。

Shell、Workspace Escape、Protected Path、凭据或配置重定向、Host-wide Tool Mutation、Package Publication / Ownership，以及明显破坏性的基础设施操作，仍然是硬边界。

我最后留下了一段很实用的中间地带：动作本身允许，但这一次要执行的 Workspace、Program、Arguments 和 Working Directory 必须让我看清楚再批。

这版主要在收执行摩擦#

parallel、context、LSP、authorization 这些改动看起来分散，实际都来自我自己使用时反复碰到的几类浪费：模型重复确认已经知道的事实、明明可以并行却串着查、语义服务状态不清楚、命令到了最后一步才发现权限不够。

v0.6 做的就是把这些信息提前放进 Runtime 能确定的位置，尽量少让模型靠 Prompt 猜。

我也不会给 v0.6 编一个“通用提速百分比”。真实收益取决于任务图、仓库、Host 是否支持并行调用，以及 Semantic Session 是否已经热起来。

后面的 v0.6.1，我又继续把 parallel_tools 调度器改了一轮。那次处理的是另一个更底层的问题：并行任务不应该因为同一层里有一个慢分支，就集体等它。

wcode v0.5：LSP 不再每次现启

Sun, 30 Aug 2026 17:30:00 +0800

v0.4 做完以后，我以为 wcode 写代码这条主链已经比较顺了。

那一版主要解决 Context 成本：agent_context 变成 Coding Entry，Repo Map 有了 Cache 和 Scope，简单任务不需要每次把整个项目重新理解一遍。

但真的继续拿它写代码，很快又遇到另一个问题。

不是“找不到函数”。

Tree-sitter 和 Search 对定位其实已经很好用了。

真正麻烦的是这种问题：

谁在调用这个函数？
这个 Trait 到底有哪些实现？
改这个 Symbol 会影响哪些跨文件 Reference？
这个调用关系是同名文本，还是类型系统真正解析出来的？

这种时候，grep 能找到很多东西，但不一定完整；Tree-sitter 能告诉我语法结构，但它也不应该假装自己知道类型系统。

所以 v0.5 没继续堆零散的 LSP API，我直接把 Language Server 的生命周期重新做了一遍，让它可以受限地常驻和复用。

我为什么没有把所有查询都切到 LSP#

最直接的做法其实很诱人：

既然 Language Server 更懂代码，那以后 Definition、Search、Reference、Call 全走 LSP 不就好了？

我试着沿这个方向想了一轮，最后放弃了。

原因是 Agent Coding 里有两类完全不同的问题。

第一类只是定位：

这个函数在哪？
这个 Struct 定义在哪？
哪个文件包含这个字符串？

这类问题 Tree-sitter / Search 很便宜，而且稳定，不需要启动项目语义环境。

第二类才是真正需要 Semantic Completeness 的关系问题：

references
implementations
incoming callers
outgoing callees
rename impact

如果为了第一类问题也默认走 Language Server，就会把一个本来很便宜的定位动作变成进程启动、Initialize、Document Sync、Semantic Query。

而 Agent 还有一个额外成本：Tool Result 最后会进入 Context。

所以我现在更愿意把两层能力分开：

                ┌──────────────────────┐
                │     agent_context     │
                └──────────┬───────────┘
                           │
                普通定位   │   跨文件关系
                           │
          ┌────────────────┴───────────────┐
          ↓                                ↓
find_symbol / search_code          semantic_navigation
Tree-sitter / text search                 │
          │                               ↓
          │                       Warm LSP Session
          └──────────────┬────────────────┘
                         ↓
                    edit / review
                         ↓
                    verify_project

不是“LSP 比 grep 高级，所以替掉 grep”。

而是让每一层只解决它真正擅长的问题。

以前的 LSP 其实还是一次性工具#

wcode 之前已经能跑 Language Server。

但生命周期很像一个 Batch Job：

start provider
  ↓
initialize
  ↓
didOpen
  ↓
Document Symbol
Call Hierarchy
Implementation
  ↓
shutdown

它适合定期补 Software Graph。

但如果 Agent 紧接着又问一次 Reference，就要重新付一遍启动成本。

更关键的是，这种模型下“Semantic Provider”在架构上仍然只是一个索引器，不是真正的 Runtime。

v0.5 把这个生命周期改了。

现在 Harness 里有一个有界 Session Pool：

Workspace
   ↓
Provider + Binary Identity
   ↓
Warm Session Slot
   ├── graph refresh
   ├── semantic_navigation
   ├── didChange
   └── didClose

同一个 Workspace 下，后台 Graph Indexing 和前台 Navigation 会复用同一个 Provider Process。

如果 rust-analyzer 已经 Warm，第二次查 Caller 不需要再启动一遍。

Warm 不等于永远不关#

我不想为了省启动成本，最后在后台养一堆永远不会退出的 Language Server。

所以这个 Pool 从一开始就是 Bounded 的。

它有几条约束：

Session 数量有上限；
Idle Slot 会淘汰；
同一个 Slot 的 JSON-RPC Stream 串行处理；
Provider Process 死掉以后重建；
Provider Binary Identity 变了以后重建；
Workspace Key 不共享到别的项目；
离开当前有界索引集合的 Document 会 didClose。

发版前我专门沿这条生命周期又审了一遍，结果真的抓到一个边界 Bug：最初的 Idle Eviction 其实是 Lazy 的，只有下一次有人访问 Session Pool 时才会 Prune；更糟一点，容量满时如果直接从 Map 里移除“最旧 Slot”，这个 Slot 可能还被一个 Active Request 持有，于是 Map 看起来仍然只有 16 个，实际进程却可能短暂跑到第 17 个。

最后我把规则改成了更保守的版本：

Idle + unleased
  → 可以 prune

capacity full + 有 unleased slot
  → 只驱逐 unleased slot

capacity full + 全部 leased
  → fail closed / retry

provider binary changed + old slot still leased
  → 等当前 request 结束
  → 再替换

Background Semantic Coordinator 也会周期性主动 Prune，所以即使是没有 TUI 交互的 mcp-stdio，Idle Bound 也不是一句文档里的承诺。

源码变化也不是简单把 Process 杀掉重启。

现在不是强行给所有 Server 发同一种 Notification，而是先看它在 initialize 里声明的 textDocumentSync：

Full
  → Open 发完整内容
  → Change 发整文档

Incremental
  → Open 发完整内容
  → Change 用旧文档范围做合法 replacement
  → Range 按协商的 UTF-8 / UTF-16 / UTF-32 算

None / openClose=false
  → 不硬发 Server 没声明支持的 Notification
  → Server 继续从磁盘读取

只有 Server 要求 Open/Close Sync 时才发 didOpen / didClose。这才比较像我理解的“常驻语义层”：它既知道当前 Document Revision，也尊重每个 Language Server 自己的同步协议，而不是假定 Rust 能工作的 Change Shape 对 22 种语言都成立。

`semantic_navigation` 不让 Agent 自己算 UTF-16#

做 Agent Tool 时，我越来越不喜欢把底层协议细节原样扔给模型。

原始 LSP 通常希望调用方给：

file URI
line
character
position encoding

然后不同 Server 还可能用 UTF-8 / UTF-16 Position Encoding。

让模型自己根据源码去算 UTF-16 Offset，我觉得完全是在浪费模型能力，而且很容易在非 ASCII 代码里漂掉。

所以 v0.5 的 semantic_navigation 主入口是：

path + symbol

wcode 自己先用 Tree-sitter 找 Symbol 的精确位置，再根据 Language Server Initialize 时协商到的 Encoding 转换 Position。

Agent 只需要表达意图：

definition
hover
references
incoming_calls
outgoing_calls
implementations
impact

真正已经持有精确 Position 的调用方，也可以继续传 line + character。

这件事看起来很小，但我觉得它代表一个方向：

LSP Primitive 不应该直接等于 Agent Primitive。

Agent Tool 应该封装成模型真正想问的问题，而不是要求模型先学会协议的坐标系。

这里发版审计又抓到另一个我不愿意留到 0.5.1 的问题：最早实现里，如果 Server 声明支持 references，但这次 Request 实际 Timeout / Error，结果路径可能最后只留下一个空数组。对 Agent 来说，“请求失败”和“确实没有 Reference”完全不是一件事。

所以现在 Result 会明确分成：

unsupported
  → Server 没这个能力

failures
  → Server 有能力，但这次 LSP Request 失败

relationships = []
  → Request 成功，真的没有匹配关系

我尤其不想让失败被当成 Negative Semantic Evidence。语义系统最危险的不是“不知道”，而是失败以后还表现得像自己很确定。

22 种语言，不能只有 Rust 真正跑得通#

发版前我又给这版加了一条更苛刻的要求：

既然 wcode 对外说 Syntax Index 支持 22 种语言，那 LSP 层也不能只把 rust-analyzer 做扎实，其他语言只在 Registry 里挂个名字。

这次审计以后，我把“支持”拆成了三个完全不同的概念：

Compatibility
  → wcode 有没有正确的 Provider Adapter / Command / Language ID

Installation
  → 用户机器上有没有真的装这个 Language Server

Live Semantic
  → 这个已安装 Server 有没有真实 initialize 并回答当前 Revision

只有第一层是 wcode 在 Build/Test 阶段能 100% 保证的。

第二层取决于用户机器。

第三层必须等 Runtime 真正和 Server 完成 LSP Handshake 以后才能成立。

所以 v0.5 现在要求 22 种 Indexed Language 每一种恰好只有一个 Canonical LSP Launch Profile，并用测试把映射和 Provider-specific Argument 锁死。除此之外，我还加了一层跨平台 stdio Mock LSP：每一个 Canonical Profile 都会真的 Spawn 一个子进程，完成 initialize、Capability Negotiation、Open/Change/Close 和 Hover JSON-RPC 往返，而不是只检查数组里的字符串：

Language	Canonical LSP
Bash	`bash-language-server start`
C / C++	`clangd`
C#	`csharp-ls`
CSS	`vscode-css-language-server --stdio`
Dart	`dart language-server --protocol=lsp`
Elixir	ElixirLS `language_server.sh` / Wrapper
Go	`gopls serve`
HTML	`vscode-html-language-server --stdio`
Java	`jdtls -data <unique state>`
JavaScript / TypeScript / TSX	`typescript-language-server --stdio`
Lua	`lua-language-server`
OCaml / Interface	`ocamllsp`
PHP	`phpactor language-server`
Python	`pyright-langserver --stdio`
R	`R --no-echo -e languageserver::run()`
Ruby	`ruby-lsp`
Rust	`rust-analyzer`
Swift	`sourcekit-lsp`

而且这次不是把旧 Registry 原样拿来写测试。

我对着各家的当前启动方式重新过了一遍，确实发现了几个容易变成“纸面支持”的地方：

Go 明确改成 gopls serve；
JDT LS 会拿一个 Workspace + Runtime 唯一的用户级 -data 目录，避免两个项目或两个 wcode Process 共用 JDT State；
Dart 使用 dart language-server --protocol=lsp，并带上 wcode 的 Client ID / Version；
Elixir 同时识别官方 language_server.sh、Windows Wrapper 和常见发行版 elixir-ls；
LuaLS 对 Symlink 启动比较特殊，所以不能照抄 rustup Proxy 的处理方式，发现 Symlink 时会执行 Canonical Target；
OmniSharp 的 -lsp 不再被拿来凑 C# Fallback 数量，C# Canonical 路径只认 csharp-ls。

真正有意义的 Alternate 只留了三个：

PHP     phpactor → intelephense
Python  pyright  → pylsp
Ruby    ruby-lsp → solargraph

更重要的是，Fallback 不是只存在配置表里。

现在 semantic_navigation 和手工 semantic_provider_refresh 都会在：

canonical executable exists
        ↓
initialize fails
        ↓
try installed alternate

但 Alternate 不会继承 Canonical Provider 的授权。

如果它属于非 Automatic Provider，就必须拿自己的 Workspace + Provider + Binary Identity Trust；Refresh 成功切换以后，结果里还会显式记录 fallbacks。

所以这里我想表达的不是“wcode 自带 22 个 Language Server”。

它当然没有。

而是：22/22 的 Adapter Contract、stdio Framing 和 Provider-specific Launch Profile 是 wcode 自己要负责的；External Server 是否安装要诚实报告；Semantic Precision 只有那份真实 Binary Live Initialize + 当前 Revision Response 以后才成立。

这比在 README 里写一个长长的“Supported Languages”列表可靠得多。

默认开启以后，安全边界反而要更严格#

这次另一个比较大的决定，是 Hardened Semantic 默认开启。

也就是说普通启动：

wcode --workspace "$PWD"

如果项目里有 Rust，而且系统里有可用的 rust-analyzer，wcode 会自动维护这条 Semantic Lane。

但我没有把“所有 LSP 默认信任”一起打开。

v0.5 当前只有 rust-analyzer 进入 Automatic Profile。

因为 Language Server 和普通 Parser 不一样：它会读项目配置，有些 Server 甚至可能间接执行 Repository-controlled Code。

所以默认 Profile 做了几层限制：

Executable 必须解析到 Workspace 外；
Workspace 里的假 rust-analyzer 不会被执行；
Credential 和 Execution-injection Environment Variable 会清理；
Build Script 关闭；
Proc Macro 关闭；
Cargo Auto Reload 关闭；
Check-on-save 关闭；
Result 最后仍重新经过 Workspace Boundary Filter。

这不是 OS Sandbox。

我不想用“安全模式”这种词让人误以为 Language Server 完全没有执行面。

它只是一个我愿意默认打开的、被明显收窄过的 Profile。

如果是 clangd、Pyright、gopls 或其他当前还没有 Hardened Profile 的 Provider，仍然需要显式 RiskyExecution Trust。

而且 Warm Session 出现以后，授权语义也跟着变了。

以前一次性 Provider 可以按某次 Refresh Operation 授权。

现在 Process 会被复用，真正准确的 Trust 应该是：

Workspace
  + Provider
  + current Provider Binary Identity

这个 Binary Identity 也不能漏。发版审计时我发现，第一版 Provider-session Fingerprint 只绑定了 Provider ID；如果 PATH 上同名 Provider Binary 被替换，Session Key 会重建，但旧授权理论上仍可能继续适用。现在 Authorization 和 Warm Session 使用同一套 Provider Binary Identity：Executable 被替换以后，旧 Grant 不会继承过去。

因此同一份已批准 Provider 可以被 Refresh 和 Navigation 复用，不会每问一次 Reference 又弹一次权限；但它也不会顺手授权替换后的 Binary。

如果完全不希望 wcode 启动第一方 Language Server：

wcode --workspace "$PWD" --no-semantic

Tree-sitter / Search 仍然都在。

后台自动维护也不能绕过全局资源边界#

另一个我不想接受的状态是：

前台 Tool 都有 Global Semaphore，后台 Semantic Worker 却偷偷无限跑。

那 TUI 上看到的并发数就会是假的。

所以 Background Semantic Maintainer 也必须先拿 Harness Permit，再真正进入 Running。

生命周期还是：

queued
  ↓
acquire global permit
  ↓
running
  ↓
completed / failed

Broad Workspace 下面如果还有具体 Project Subspace，也只让最具体的 Leaf Workspace 启动自动 Semantic Worker。

不然我把 ~/Code 暴露给 wcode 时，父目录和十几个子项目会同时索引同一批源码。

这种优化不会出现在“支持哪些 LSP”的 Feature List 里，但我觉得比多支持一个 Server 更重要。

TUI 现在能看出 Warm 到底有没有生效#

以前 TUI 的 LSP 状态主要是：

available / runnable
fresh / stale

v0.5 现在还会显示：

warm sessions
synced documents
provider starts
semantic queries

我特意加这些，不是为了让 Dashboard 再多几个数字。

而是 Warm Runtime 最容易出现一种假优化：代码里写了 Cache，但实际上每次 Query 还是重启 Process。

如果 Session Start 一直涨、Query 也一直涨，那我就知道复用没有真的工作。

可观测性是性能优化的一部分，不是最后补的 UI。

v0.4 和 v0.5 的差别#

如果 v0.4 是“让 Intelligence 不要变成 Context Tax”，v0.5 更像是“让语义能力真正进入日常 Coding Hot Path”。

	v0.4	v0.5
Semantic Provider	有界 Batch Refresh	Bounded Warm Runtime
LSP Process	Refresh 后退出	Workspace Session 复用
Document Sync	`didOpen` 为主	Server-declared Full / Incremental / None
Agent Navigation	Syntax + Graph Context	`semantic_navigation`
Default Routing	`agent_context` + Tree-sitter	Localization 走 Syntax，Relationship 才走 LSP
Automatic Trust	LSP 需要显式 Trust	Hardened `rust-analyzer` 默认开启
Non-auto LSP	Exact Refresh Trust	Workspace + Provider Session `RiskyExecution`
TUI	available / fresh	available → launch-ready → live + warm/fresh

我觉得这已经不是 0.4.x 的 Patch。

所以版本直接到了 v0.5.0。

这次发版我也把 Release Boundary 再收紧了一次#

Milestone Release 最怕的不是功能没写完，而是“仓库里的版本看起来有六个答案”。

wcode 现在除了 Cargo Version，还有 Agent Plugin / Marketplace Manifest。

v0.5 发版前我把它们统一成同一个版本，并且不只依赖 CI Shell Script 检查。

Unit Test 也会验证：

Cargo package version
  == plugin.json
  == Claude plugin
  == Codex plugin
  == ZCode plugin
  == root marketplace
  == plugin marketplace

Release Workflow 还会再独立检查一次，然后跑：

Design / Traceability / Product Scope gate
Format
Check
Clippy --all-targets
Linux test
macOS test
Windows test
Linux / macOS / Windows release build
binary --version
SHA256SUMS

这次 Tag 前最后一轮本地 Full Gate 是：

git diff --check                       ✅
cargo check --locked                   ✅
cargo fmt --check                      ✅
cargo test --locked                    ✅ 270 passed / 0 failed
cargo clippy --locked -- -D warnings   ✅
cargo build --release --locked         ✅

这里的 270 个核心测试已经包含 22 个 Canonical Profile 的真实 stdio Mock-LSP Initialize Contract、Full/Incremental/None Document Sync、Warm Session Capacity/Idle、Provider Binary Trust、Fallback 和 Navigation Failure Semantics。

我仍然不想把“本机 cargo test 绿了”直接等同于“Release 已经成立”。

真正发布的是 Tagged Revision 和对应 Artifact；Linux/macOS/Windows 的最终跨平台结论继续交给 Tag CI。

最后#

wcode 最开始只是我为了让 Web AI 安全碰本地代码写的一层 MCP Bridge。

后来它慢慢有了 Design State、Software Graph、Verification、Evidence、Reconciliation。

v0.4 我开始对 Agent 的 Context 成本负责。

到 v0.5，我又多了一层判断：

代码智能不应该只有“便宜但不完整”和“准确但每次很重”两个极端。

Tree-sitter / Search 可以一直做便宜、稳定的定位底座。

Language Server 则应该在真正需要关系完整性的地方，以受限、可复用、可观测的 Runtime 形式出现。

不是把所有东西都升级成 LSP。

而是让 Agent 知道：什么时候 Syntax 已经够了，什么时候值得支付 Semantic Cost。

这应该会是后面 wcode Semantic Runtime 继续扩展其他语言时最重要的一条原则。

代码：https://github.com/francis-du/wcode

文档：https://wcode.francis.run/

v0.5.0 Release Notes：https://wcode.francis.run/docs/releases/v0.5.0/

wcode v0.4：我开始压 Context 和 Tool Call

Thu, 27 Aug 2026 23:55:00 +0800

v0.3 做完以后，wcode 已经有 Design State、Software Graph、Traceability、Risk、Verification、Evidence、Reconciliation 和 Project Observatory。

从“能力列表”看，其实已经很多了。

但我拿它真的去写几个项目以后，最明显的问题反而很朴素：Agent 已经知道怎么做了，前面还是花了太多 Context 和 Tool Call。

所以 v0.4 我先没加新的大能力，主要把写代码这条默认路径重新压了一遍。

v0.4 先不加大功能#

v0.3 我最关心的是“软件状态能不能留下来”。

所以那一版的主线是：

Design State
   ↓
Software Graph
   ↓
Drift / Impact / Risk
   ↓
Verification / Evidence
   ↓
Reconciliation

这些东西 v0.4 都还在。

但如果一个 Agent 每次只是改两行代码，也要先完整走一遍 Design、Graph、Traceability、Risk，再查 Symbol、再读文件，那这套系统会越来越像“为了完整而完整”。

我不想让 Intelligence 本身变成新的 Context Tax。

所以 v0.4 的默认 Coding Path 变成了：

agent_context
    ↓
必要时补 symbol_context
    ↓
apply_edits / apply_file_edits
    ↓
review_changes
    ↓
verify_project

更深的 Design、Graph、Risk、Reconciliation 还在，但变成按任务需要进入，而不是每次启动都强制付费。

`agent_context` 成了真正的 Coding Entry Point#

这一版我加了一个 Agent Context Compiler。

它不是简单把几个 Tool Result 拼起来，而是尝试一次返回“现在就可以开始修改”的最小上下文。

一个典型结果里会有：

任务相关 Design / Constraint
Direct Target
Exact SHA
Scoped Repo Map
Related Symbol / Test
Working-tree Advisory
Readiness
Next Actions
必要时的 Hot Source

我最在意的是最后几个东西。

以前 Agent 经常出现这种链：

project_context
→ search
→ find_symbol
→ read_file
→ 再 search
→ 再 read_file
→ edit

每一步都合理，但累计起来 Tool Round-trip 很多，而且每次响应都会重新占一部分 Context。

现在如果任务足够明确，agent_context 可以直接把最强目标连同 SHA 和一小段 Hot Source 带回来。

常见的小修改就能变成：

agent_context → edit

这对我来说比“又多支持一个 Tool”有意义得多。

Context Budget 不应该永远是一个固定数字#

以前 software_context 更像一个固定预算的 Query。

但真实 Coding Task 差别很大。

改一个错误文案和改一个跨 Runtime / MCP / Workspace 的安全问题，不应该拿同样大的上下文。

所以 v0.4 里，agent_context 在不显式传 Budget 时会做 Adaptive Budget。

大致思路是：

明确单点任务
  → 小 Context

目标不确定 / 跨模块
  → 给更多 Context

始终有 Hard Bound

这个优化看起来不如 Graph 或 Verification “大”，但 Agent 每一次调用都会碰到它。

我现在越来越觉得，做 Agent Runtime 不能只优化模型能不能完成任务，还要开始对每次完成任务花了多少上下文负责。

Repo Map 也不能每次扫完整仓库#

Agent Context 里最容易膨胀的是 Repo Map。

如果一句任务已经明确属于 workspace Scope，而且目标文件也很直接，再把 Runtime、UI、Graph、Verification 全仓库结构都送进去没有意义。

所以现在 Repo Map 有几层变化：

Scope-aware；
Cold Build 时尽量只构造相关区域；
Structure 按 Revision Cache；
每个 Query 只重算 Ranking；
多 Query Symbol Search 对一个 Source Root 只扫描一次；
Fresh Semantic / Runtime Evidence 可以提高相关 Caller / Dependency 排名；
Semantic Revision 过期以后自动退回 Syntax，不继续拿旧事实指导 Agent。

我还把这些东西做了 Telemetry。

TUI 现在可以看到 Agent Context Calls、平均 Model-visible Token、Repo-map Cache Hit，以及大概省掉了多少 Context。

不是为了做一个漂亮数字，而是我想以后优化时至少知道自己到底有没有真的减少模型负担。

Project Observatory 终于先讲架构，而不是先讲需求列表#

v0.3 的 Project Observatory 已经从“Graph 球图”改成了 Requirement-first。

到 v0.4 我又改了一次。

现在进去先看到的是整体 Component Architecture。

原因也很简单：

当我要理解一个陌生项目时，我通常第一句不是：

这个 Requirement 现在状态怎么样？

而是：

这个项目到底分成哪几块，它们怎么依赖？

所以现在 Observatory 会先把 Design 里声明的 Dependency 和代码里真实观测到的 Relationship 叠在一起。

Design Architecture
        +
Observed Implementation
        ↓
Overlay

并且继续保留 Provider / Precision。

这点我没有妥协：Tree-sitter 没看到某个关系，不等于关系不存在；只有真实 Semantic / Runtime / Deterministic Evidence 才能把某些 Observed Drift 升级成更强的判断。

UI 里也不再给一个模糊的“Health Score”，而是拆成可以解释的：

Observed Drift；
Evidence Coverage；
Implementation Coverage。

我更愿意看到几个不完美但能解释的指标，也不想看到一个 87 分却不知道为什么是 87。

我还是不想给 Agent 一个 Shell，但开发命令不能太残废#

wcode 一直坚持 No-shell Boundary。

但 v0.3 之后我自己使用时也碰到一个现实问题：真正开发不可能永远只有 cargo test 和 git status。

所以 v0.4 扩了很多 Command Policy，不过方向不是“放开命令”，而是给具体工具写具体策略。

Git 现在可以在精确授权后执行：

git add <explicit paths>
git commit -m <message>
git push <remote> <ref>

但 Force Push、Delete Ref、Mirror、Reset/Restore 这类形态仍然直接挡掉。

Push 如果被批准，也只允许通过固定的非交互 SSH 方式使用当前 SSH Agent，不会顺手把 Credential Helper 或 HTTPS Token 暴露给模型。

gh 也不是整个二进制一次性放开。

PR、Issue、Workflow、Release、Merge、Run 都有自己的 bounded shape；gh auth、gh api、Secret、Variable、Extension 这些边界仍然封死。

另外补了不少真实开发里常见的 CLI：

fd / jq
cmake / ninja
dotnet / mvn / gradle
swift / zig
pre-commit / act
cargo-nextest
Git LFS
uv / ruff / biome / deno
docker / kubectl / terraform

我希望最终状态是：Agent 能正常开发，但“能正常开发”不等于“给它一个 Terminal”。

Tunnel 也不应该因为一个 Provider 挂了就不能用#

wcode 最早的 Remote MCP 默认依赖 Cloudflare Quick Tunnel。

它很好用，但单 Provider 依赖太脆。

v0.4 现在的 Auto Path 是：

Cloudflare
   ↓ fail / missing
localhost.run
   ↓ fail
Pinggy

后两个直接走 OpenSSH Reverse Forwarding，不需要为了启动 wcode 再自动安装一个 Tunnel Client。

而且拿到 Public URL 还不算成功。

Candidate URL 必须真的访问到当前这个 wcode Runtime 的 instance-matched /healthz，否则不会被当作可用 Tunnel。

这解决的是一个很现实的问题：

Remote MCP 的网络入口应该是可恢复的基础设施，而不是“某个第三方命令今天能不能跑”。

这次顺手把几个越来越大的文件拆掉了#

做性能和 Agent Context 的过程中，有几个文件又开始长得不太舒服：

main.rs；
harness.rs；
Monitor；
command_policy.rs。

所以 v0.4 也做了一轮责任拆分。

现在 Tunnel、Harness Profile、Agent Context、Repo Map、Monitor State 都已经单独落文件。

发版前最后又把 Command Policy 拆成：

command_policy/
├── git.rs
├── github.rs
├── infrastructure.rs
└── dev_tools.rs

我没有为了“模块化”去造新的抽象层，主要目的是别让安全策略继续堆在一个 1500 行文件里。

这类代码最怕两件事：模型每次要读一大坨上下文，以及多人/多 Agent 修改时冲突越来越集中。

MCP 自己也补了一次异常隔离#

发版前我碰到过一次很典型的问题：多个 Tool 突然一起报 ExceptionGroup: unhandled errors in a TaskGroup。

受影响的不只是某一个业务 Tool，workspace_info、read_file、run_command、review_changes 都会一起失效。

这个现象说明问题已经不是 Tool 业务逻辑，而是请求隔离边界。

v0.4 最后补了一层统一的 Request Task Isolation：

HTTP 单请求独立 Task；
stdio 单请求独立 Task；
Child Panic / Cancellation / JoinError 转成正常 JSON-RPC Error；
Durable MCP Task Worker 的 Child Failure 也落成 Task Failure；
一个 Child 失败以后，后续独立 Tool 仍然可以继续工作。

Release Profile 也不再使用 panic=abort，否则“捕获一个 Child Panic 并保持 Session 可用”在 Release Binary 里根本做不到。

这个修复对正常路径没有什么新 UI，但我觉得它很重要：Tool Failure 应该是一次调用失败，不应该升级成整个 Agent Session 坏掉。

v0.4 我会怎么概括#

如果 v0.3 是“把软件状态接起来”，v0.4 更像是“让这套状态真正适合每天写代码”。

	v0.3	v0.4
Coding Entry	多 Tool 组合	`agent_context`
Context	固定/通用	Adaptive + Scope-aware
Repo Map	任务时构建	Revision Cache + Query Ranking
Source Read	多一步读取	Direct Match 可带 Hot Source
Observatory	Requirement-first	Architecture-first → Requirement Drill-down
Command Policy	基础安全命令 + Selective Approval	Git/GitHub/Dev CLI 的精确 bounded policy
Tunnel	Cloudflare 为主	Cloudflare → localhost.run → Pinggy
Runtime Failure	各路径自行处理	MCP Request / Child Task Isolation
Maintainability	拆主 Runtime Cluster	继续拆 Agent Context / Tunnel / Monitor / Command Policy
Verification	Full Gate	Full Gate + 文档 EN/ZH parity regression

发版前最后一次本地 Full Gate 是：

git diff --check                       ✅
cargo check --locked                   ✅
cargo fmt --check                      ✅
cargo test --locked                    ✅ 210 passed
cargo clippy --locked -- -D warnings   ✅
cargo build --release --locked         ✅

Design / Traceability 也还是完整的：Requirement → Component、Design → Implementation、Acceptance → Verification 都是 100%。

当然，本地绿色只是发版准备；真正的 Release 还是要以 Tagged Revision 和 CI / Release Artifact 为准。

最后#

v0.3 的时候我觉得 wcode 真正有意思的地方，是它开始不只关心“代码能不能被 Agent 改”，而是开始关心“软件为什么变成现在这样”。

v0.4 又让我多了一层判断：

如果这些 Intelligence 每次都让 Agent 付出很高的上下文和工具往返成本，它最终也不会成为默认工作流。

所以这一版看起来没有 v0.3 那么像一次产品方向转弯。

但对我自己每天用它写代码的体验来说，变化反而更直接。

现在我希望大部分任务都从一句 Goal 开始，拿到一个足够小但能动手的 Context，然后尽快 Edit、Review、Verify。

复杂任务再把 Graph、Risk、Reconciliation 拉进来。

不是让 Agent 每次都理解整个软件世界，而是让它在需要的时候，拿到刚好足够可靠的那部分。

代码：https://github.com/francis-du/wcode

文档：https://wcode.francis.run/

wcode 的授权现在怎么做

Wed, 26 Aug 2026 23:35:00 +0800

我一直不想给 Agent 一个 Shell。

但实际用久了以后，我也越来越不喜欢另一个极端：只要一个工具不在默认列表里，就永久拒绝；真要用的时候，只能重启进程加一个很宽的 Trust Flag。

这两个选择都太粗：

完全不许
   或
整个进程都信任

最近我把这些情况统一收进了 Pending Authorization Queue。模型可以把请求挂出来，最后还是我自己选哪一条批、哪一条拒绝。

为什么 `Y/N` 以前看起来没用#

TUI 其实早就有 Y/N 的 Key Handler。

问题是 UI 只在 Footer 里塞了一个 Pending 数字。

用户看不到：

到底是谁在申请？
申请哪个 Workspace？
要跑什么？
这是普通命令还是删除？
Y 到底会批准哪一条？

所以从人的角度看，Y/N 就像两个没有上下文的快捷键。

现在 Pending Request 会直接显示成一个列表。

大概是这种信息：

AUTHORIZATION REQUIRED                         3 PENDING

› AUTH-00000021 [COMMAND]      web   · authorize command: hugo
  AUTH-00000020 [RISKY EXEC]   api   · allow repository-aware command: cargo metadata
  AUTH-00000019 [DELETE]       api   · delete file: src/obsolete.rs

↑/↓ select request   Y approve selected   N deny selected

Y 不再是“批准最新一条”。

它只批准当前选中的 Request。

N 也一样。

当多个 Agent / Tool 同时工作时，这个区别很重要。

命令授权不再被默认 Catalog 封死#

最开始 wcode 有一份固定 Command Catalog：

cargo
rustc
git
rg
npm
pnpm
yarn
bun
node
python3
pytest
go
make

它很适合作为默认预授权集合。

但把它当成“用户永远只能授权这些命令”的上限，就会变得很别扭。

真实项目会用：

hugo
flutter
deno
mvn
gradle
swift
mix

甚至公司内部还有自己的 Build Tool。

所以现在语义变成：

默认安全集合 → 直接进入后续 Command Policy

其他合法 bare executable
        ↓
CommandAccess Pending Request
        ↓
用户批准
        ↓
只加入当前 Workspace 的运行时 allowlist
        ↓
模型重试

这不是让模型自己扩权。

第一次请求仍然失败。

真正改变权限的是本地用户的批准动作。

为什么我还是不让它授权 `bash`#

“用户可以授权模型请求的命令”不等于“所有字符串都应该变成可授权请求”。

wcode 仍然有一层不能被 UI 点掉的硬边界。

Program 必须是合法的裸可执行程序名：

hugo        ✓
flutter     ✓
gradle      ✓

./tool      ✗
../tool     ✗
/usr/bin/x  ✗
foo/bar     ✗

Shell Interpreter 也永久拒绝：

sh
bash
zsh
fish
pwsh
powershell
cmd

原因还是同一个。

wcode 的 Command Contract 是：

program + args[]

而不是：

shell -c arbitrary_string

如果允许模型拿到 Shell，前面的 Argument Inspection、Protected Path Check 和 No-shell 边界都会变得很容易绕。

我宁愿让用户授权更多具体 Program，也不想把整个模型重新变成远程 Terminal。

`CommandAccess` 和 `RiskyExecution` 是两层#

这个地方容易混。

假设模型第一次想跑：

hugo --minify

如果 hugo 还没被当前 Workspace 授权，先得到的是：

CommandAccess

它回答：

这个 Program 能不能出现在这个 Workspace？

但对已经有专门 Policy 的命令，例如 Cargo / Go / Package Manager，某些参数可能会执行 Repository-controlled Code。

这时即使 Program 已经允许，仍可能得到：

RiskyExecution

它回答的是另一件事：

这组具体 repository-aware Operation 是否值得信任？

所以权限不是一个 Boolean。

更接近：

Program Access
      ↓
Argument / Path Policy
      ↓
Risky Operation Trust
      ↓
Execute

现在有四类 Authorization#

当前我把它们分成四种。

1. CommandAccess#

模型请求当前 Workspace 尚未授权的 Program。

批准以后，这个 Program 加进当前 Workspace 的运行时 allowlist。

2. RiskyExecution#

Program 本身允许，但这组参数可能加载或执行仓库控制的代码、配置或插件。

批准的是精确 Operation Fingerprint 的 Session Grant。

3. RuntimeExecutor#

Property / Mutation / Fuzz / Runtime Canary 等 Verification Executor 可能来自仓库配置。

它们是另一条显式 Trust Boundary。

4. DestructiveDelete#

这是最严格的。

只能删除一个普通文件或空目录，文件要求当前 SHA，批准是 exact one-shot，用一次就失效。

我不想让一个“同意删除”自动变成当前 Session 后续所有 Delete 都合法。

WebUI 也必须能处理同一批 Request#

只在 TUI 做授权有个现实问题：我可能正盯着浏览器里的 Project Observatory，而不是 Terminal。

所以现在 WebUI 的 Manage access 里有三块：

Authorized projects
Authorized commands
Pending authorizations

Project 可以在运行时添加。

Command 可以手动授权或撤销。

Pending Request 则逐条显示 Approve / Deny。

WebUI 并不是另开了一套权限状态。

它和 TUI 操作的是同一个 Authorization Manager。

也就是说：

Model Request
      ↓
one shared Pending Queue
   ↙              ↘
TUI               WebUI
Y / N         Approve / Deny
   ↘              ↙
 same runtime authorization state

WebUI 的这些 API 仍然需要原有的 Local UI Token 和 Origin Validation。

不能因为它是“管理页面”，就变成一个没有保护的本地管理接口。

多 Workspace 时，授权必须跟着项目走#

我还顺手修了一个容易忽略的问题。

如果同一个进程同时暴露：

backend
frontend
website

CommandAccess 必须知道自己属于哪个 Registry Workspace ID。

不能只根据目录 basename 猜，也不能批准一次以后给三个项目一起放开。

所以现在授权 Request 会带精确 Workspace ID。

批准 website 的 hugo，不会顺手让 backend 也能跑 hugo。

这是我想要的权限粒度。

授权以后仍然不是 OS Sandbox#

最后还是要强调这一点。

这些授权机制解决的是：

谁可以请求什么
谁决定放行
放行到什么粒度

它不是操作系统级 Sandbox。

一个用户批准的 Program 本身仍可能做很多事情。

wcode 能继续保证的是它自己的边界：

不经过 Shell；
Workspace-relative CWD；
Program Name 不允许路径；
Argument 不允许 Workspace Escape；
Protected Path 继续拒绝；
敏感环境变量继续清理；
Git Helper / Mutation 等专门 Policy 继续生效；
Timeout 和输出上限继续存在。

所以授权按钮的含义不是：

这个命令绝对安全。

而是：

我知道模型为什么需要它，我愿意把这一层权限交给当前 Workspace。

这个语义对我来说更诚实。

v0.3 的完整变化见 wcode v0.3：从本地代码桥到 Software Intelligence Runtime，底层安全边界继续看我还是不想给 Agent 一个 Shell。

wcode v0.3：它已经不只是一个 MCP Bridge 了

Wed, 26 Aug 2026 23:30:00 +0800

wcode 的 v0.3 是一次比较明显的方向变化。

v0.2 发布时，我给它的定位还很简单：一个轻量的 Code Agent plugin，把已经在用的 AI Client 接到本地仓库。

这个定位没有消失。Remote MCP、OAuth、Workspace、Tree-sitter、代码读写、Git Review 和 Verification 这些底层能力都还在。

但如果只看 v0.3 的代码和界面，它已经不太像一个“桥”了。

到 v0.3，我已经不太把它当成一个单纯的“桥”了。模型还是写代码，wcode 开始额外保存设计、变化、风险和验证这些仓库状态。

v0.2 当时解决了什么#

我重新看了一遍 v0.2 Tag 里的 README。

当时的主线非常明确：

AI Client
   │
   │ Remote MCP + OAuth
   ▼
wcode
   │
   ├─ search
   ├─ symbols
   ├─ read / edit
   ├─ project context
   ├─ git review
   └─ verification
   │
   ▼
configured workspace roots

一句话就是：不要再造一个 Agent，把本地代码能力安全地提供给现有 Agent。

v0.2 已经有不少我现在仍然很看重的基础：

一个 Rust 原生二进制；
Remote MCP + OAuth 2.1 / PKCE；
Cloudflare Quick Tunnel；
多客户端接入；
Workspace Root 隔离；
Tree-sitter Symbol Navigation；
SHA-256 Guarded Edit；
Git-aware Review；
有界并发和实时 TUI。

但它回答的主要还是：

模型怎么安全地碰本地代码？

v0.3 想回答的问题已经变成：

多个模型、人和工具不断修改一个项目以后，怎么还知道这个软件为什么是现在这样？

这版我先把 Design State 接进来了#

v0.3 里最重要的东西不是某个新 Tool，而是 .wcode Design State。

它把长期应该稳定存在的意图放进仓库：

Requirement
Component
Constraint
Acceptance Criterion
Decision

这些东西不是 Markdown 里的描述，而是带稳定 ID 和关系的结构化 Desired State。

于是一个功能可以真的形成链路：

Requirement
    ↓
Component responsibility
    ↓
File / Symbol
    ↓
Acceptance Criterion
    ↓
Test / Verification

这也是为什么 v0.3 之后，wcode 不再只是给模型提供 read_file / apply_edits。

Agent 可以先从需求和设计开始理解，再落到代码。

Product Scope 把大仓库重新分区#

只做 Design State 还不够。

仓库一大，Agent 还是很容易把整个项目看成一个平面目录。

所以 v0.3 有了 canonical Product Scope Registry：

runtime
integrations
workspace
design
graph
semantics
traceability
risk
verification
evidence
reconciliation
experience

它同时参与源码架构分类、scope_status、software_context、MCP Tool Metadata 和 Agent Workflow。

我现在给 Agent 一个任务时，可以先确定它属于哪个 Product Scope，再缩小上下文。

这比“先 grep 全仓库再说”稳定很多。

Software Graph 不再只是一个索引#

Tree-sitter 仍然是 always-on 的语法底座，但 v0.3 把 Graph 扩成了可以混合多种 Provenance 的 Software Digital Twin。

基础事实仍明确标注：

provider = tree-sitter
precision = syntax

如果真实 Language Server 返回 Document Symbol、Call Hierarchy 或 Implementation，才会进入 semantic precision。

外部 SCIP / Compiler / Runtime Provider 也可以进入同一张 Graph，但每条关系都保留自己的 Provider、Precision 和 Revision。

Graph 现在还会保留 meaningful revision history，可以看节点和关系到底怎么变，而不是只看当前快照。

v0.3 的主界面不是 Graph 球图#

我做过一版能拖、能缩放的 Graph Canvas。

后来删掉主视图了。

不是 Graph 没用了，而是“看一团节点”不是我真正想解决的问题。

现在 WebUI 是 requirement-first 的 Project Observatory：

Desired State
    ↓
Actual State
    ↓
Change
    ↓
Proof
    ↓
Convergence

一个 Requirement 下面可以直接看到：

功能意图；
Component 责任和声明依赖；
当前真实实现；
Acceptance / Verification；
Constraint / ADR；
当前 Git Change；
Evidence；
Convergence Blocker；
Graph Revision。

TUI 按 W 会直接打开当前焦点 Workspace 的 Project Observatory。

Verification 从“跑过测试”变成 Evidence#

v0.2 已经有 verify_project。

v0.3 里 Verification 的变化，不是多跑几个命令，而是结果开始有身份和 Revision。

现在可以记录：

谁产生的 Evidence
针对哪个 Code Revision
针对哪个 Design Revision
使用什么 Policy
结果是 Pass / Fail / Disagree / Inconclusive

Property、Mutation、Fuzz、Runtime Canary、Blind Reviewer 和 Human Approval 也进入同一套 Verification Mesh。

最重要的是：新的 Pass 不会把另一个 Producer 的 Fail 擦掉。

分歧就是 Evidence，而不是需要被 UI 平均掉的噪音。

Reconciliation 把“一次聊天”变成可继续的状态#

v0.2 的典型开发闭环更像：

read → edit → test → done

v0.3 开始把“什么时候真的算 done”做成显式状态。

Reconciliation Plan 会把 Drift、Impact、Risk、Implementation 和 Verification Requirement 组织成有依赖的任务。

这些任务可以 Claim、Submit、Retry，并且持久化。

所以一个模型写代码、另一个模型 Review、第三个模型补测试，不需要共享同一个聊天上下文。

它们面对的是同一个软件状态和同一组 Evidence。

Workspace 权限也比 v0.2 更细#

v0.2 的安全模型已经强调：不给模型一个 Shell。

v0.3 继续保留这个原则，但授权粒度细了很多。

现在模型如果请求一个还没有授权的裸可执行程序，例如：

hugo
flutter
deno
mvn
gradle

wcode 不会因为它不在默认列表里直接永久拒绝，而是生成一个当前 Workspace 的 CommandAccess Pending Request。

TUI 会显示待授权列表：

↑/↓ 选择
Y    批准当前请求
N    拒绝当前请求

Project Observatory 的 Access Panel 也能处理同一批 Pending Request，并管理 Workspace 和已授权命令。

批准的是这个 Workspace 的这个 Program，不是开放一个 Shell。

bash、sh、pwsh、cmd 这类 Shell Interpreter，以及带路径的 Program Name，仍然是硬边界。

Repository-aware Argument 还可能再触发单独的 RiskyExecution 授权。

删除则仍然更严格：exact one-shot。

并发和写入也做了实际性能优化#

v0.2 已经支持有界并发，但 v0.3 的 Scheduler 已经可以理解 Read / Write / Create / Move / Delete 的路径冲突。

当前默认全局并行度调整成：

logical CPU × 12
clamp 96..192
hard max 256

同一个文件的多个 apply_edits 如果 SHA 相同、Range 不冲突，可以先合并再提交。

另外这次还专门处理了我在真实项目里感觉到的“写代码还是慢”：

交互式小文件写入保留同目录临时文件 + atomic replace，但不再每次都强制 data fsync + directory fsync；
project_context 的 Convention Scan 和 Language Quality Scan 并行执行；
search_code/search_many 改成目录遍历过程中直接进入并行搜索，不再先收集完整文件列表；
多 Edit 共享一次 Line Index；
read_file 不再先给整个文件分配一份 Line Vector；
Project Context 会明确让 Agent 优先用 apply_file_edits / create_files 做批量写入。

安全边界没有因为这些优化被拿掉：SHA、Atomic Replace、Path Isolation、Symlink / Hardlink、Protected Path 仍然存在。

v0.2 → v0.3，我会怎么概括#

如果只留一张表，大概是这样：

	v0.2	v0.3
产品中心	Local Code Bridge	Software Intelligence Runtime
模型关系	给现有 Agent 本地工具	模型是可替换 Builder / Reviewer
Desired State	无	Design State
源码边界	Workspace	Workspace + Product Scope
Code Intelligence	Tree-sitter Symbol	Composite Software Graph + Provider Provenance
改动理解	Git Review	Drift + Impact + Risk
验证	Project-native checks	Verification Mesh + Revision-exact Evidence
长任务	普通 Tool Call	MCP 2026 Durable Tasks
完成状态	一次调用结束	Reconciliation / Convergence
UI	TUI + Setup Hub	TUI + Setup Hub + Project Observatory
授权	粗粒度 Trust Flag	Pending Request + TUI/WebUI selective approval

v0.2 解决的是“把 AI 接进来”。

v0.3 更像是在回答：“接进来以后，怎么让这个项目长期不失控。”

我现在觉得这才是 wcode 真正有意思的方向。

相关实现细节可以继续看 wcode 最近做成什么样了、Design State、Verification、授权中心和 Security。

后续的写代码热路径、Agent Context、Architecture-first Observatory 和精确命令策略，继续写在 wcode v0.4：开始为 Agent 的上下文成本负责。

wcode：我还是不想给 Agent 一个 Shell

Wed, 26 Aug 2026 03:17:00 +0800

wcode 第一版里，我花时间最多的其实不是 MCP。

是 Workspace。

因为把模型接到本地仓库以后，最危险的从来不是它看错一个函数，而是 Tool Runtime 的边界没守住。

上层现在已经有 Design State、Graph、Reconciliation、Verification，复杂了很多。但越往上加东西，我越不想动底下这几条线。

Root 不是字符串前缀#

最偷懒的 Workspace 隔离大概是：

path.starts_with(workspace_root)

这当然不够。

wcode 启动时会先 Canonicalize Root，文件系统根目录、Home 这种过大的范围默认不接受，多个 Workspace 也不能随便父子重叠。

后续文件操作还会重新确认 Root。

Unix 上会记 Device / Inode，所以服务启动以后，如果同一个路径被换成了另一个目录，字符串虽然没变，身份已经变了，也会停下来。

模型传进来的路径只能是相对路径。

..、绝对路径、Windows Prefix、受保护的凭据和 VCS 路径，都是 Workspace 层直接挡，不靠 Agent 自觉。

Symlink 是我早期低估过的坑#

只拦 .. 看起来像是做了 Path Traversal 防护，实际上一个 Symlink 就能把你带出去。

所以 Workspace Path 的 Component 里有 Symlink，直接拒绝。

已有文件和新文件还不能完全用同一种检查方式。

已有文件能解析最终目标；新文件的叶子还不存在，只能先确认父目录安全，再创建。

Unix 上写 Hard Link 也有限制，因为同一个 inode 可能从另一个名字被修改。

这些逻辑写起来比一个 canonicalize() 麻烦很多，但这是我不太愿意“简化”的地方。

SHA 是防 Agent 和我互相踩代码#

文件读出来以后，wcode 会给当前 SHA-256。

后面修改已有文件，必须把这个 SHA 带回来。

这个机制最常见的用途不是防攻击，而是防一个很普通的并发场景：Agent 读了版本 A，在它思考时我手动改成了版本 B，它最后还拿 A 的上下文回来写。

没有 SHA，很容易把我的 B 一起覆盖掉。

真正提交写入前还会拿锁、重新解析路径、重新读内容、再校一次 Hash。

最后用同目录临时文件做原子替换，而不是直接 truncate 原文件。

这层我实际遇到过几次救命的情况，所以一直保留得很死。

Delete 后来加了，但故意做得很烦#

第一版 wcode 干脆没有 Delete Tool。

后来实际 Coding Workflow 里确实有删除文件的需要，所以最终还是加了 delete_path。

但它不是普通 Write。

第一次调用只会产生一个本地 Authorization Request。我要在 TUI 或受保护的 Project Observatory 里批准这个精确操作，Agent 再重试。

而且授权是 one-shot。

普通文件删除要求当前 SHA；目录只能删空目录；递归删、Workspace Root、Protected Path、Symlink、Hard-linked File 都不开放。

这会让“帮我顺便清理十几个目录”没那么丝滑。

我接受这个麻烦。

恢复一个误删目录比多确认几次麻烦得多。

`run_command` 还是不经过 Shell#

这一条从第一版到现在没变。

命令执行是：

program + args[]

不是：

/bin/sh -c "..."

所以：

&&
|
>
$(...)

这些语法根本没有解释器去理解。

默认预授权 Command Policy 仍然很窄，主要是受约束的 Git / ripgrep，以及 Harness 能确定形状的工程检查。

但现在“默认没授权”不等于“永远不能授权”。模型如果请求一个合法的裸可执行程序名，例如 hugo、flutter、deno、mvn，第一次会生成当前 Workspace 的 CommandAccess Pending Request。TUI 里可以用 ↑/↓ 选中某一条，Y 只批准选中的请求、N 只拒绝选中的请求；Project Observatory 的 Access Panel 也能处理同一批 Pending Request。

批准后只是把这个 Program 加进当前 Workspace 的运行时授权，不是开放 Shell。bash、sh、pwsh、cmd 这类 Shell Interpreter 和带路径 Program Name 仍然硬拒绝；Argument 继续经过 Workspace Escape、Protected Path 和具体 Command Policy 检查。

Git Mutation 会被挡，敏感环境变量会清掉，输出有限制，进程有 Timeout。

我一直不认同“既然模型已经能写代码，不如直接给它 Terminal”这种推导。

写代码能力和拿到一个继承了我所有环境的 Shell，不是一个权限级别。

高风险执行现在可以按操作授权#

这一块和第一版相比变过。

以前要跑 Language Server、Runtime Executor 这类 repository-aware 操作，基本就是启动时加：

--allow-risky-exec

这个开关现在还在，含义更像“这个 wcode 进程我整体信任，可以做这类执行”。

但我不一定每次都想放这么宽。

现在具体的 Risky Execution 也可以先触发本地 Authorization Request。我在 TUI 或受保护 WebUI 里批准当前 Session 的精确 operation，再让 Agent 重试。

例如我只想允许一次 Semantic Refresh，就不必顺便授权后面所有仓库执行。

这和 CommandAccess 是两层：前者决定“这个 Program 能不能在这个 Workspace 出现”，后者继续决定“当前这组 repository-aware 参数是否值得信任”。

这不是 OS Sandbox。

只是把“你信不信这个仓库里的代码会被执行”从一个粗开关拆得更细一点。

并发写入也不是谁先抢到锁谁赢#

现在 parallel_tools 能处理一部分独立 Workspace Write，这又多了一个安全问题：两个任务到底能不能同时跑。

Scheduler 会先建立 Path Resource Model。

如果两个操作碰同一个文件，或者 Move / Delete / Create 之间有父子路径依赖，就排序，不硬并发。

同文件 apply_edits 只有 SHA 一样、Edit Range 不冲突时才会合并成一次原子提交。

我不想让“支持并发”最后变成“把 race condition 交给文件锁处理”。

能不能并发应该在执行前就尽量说清楚。

安全边界不能只写在 Prompt 里#

我还是会在 Skill 和 Agent Instructions 里写：不要逃出 Workspace，不要绕过授权，不要自己扩大 risky execution。

但这些只能算工作习惯。

真正的安全边界必须在 Tool Runtime。

模型理解错了、Prompt Injection 进来了、路径算错了，最后应该撞在 Workspace Policy / Authorization / Command Policy 上。

而不是靠一句：

请严格遵守安全规则。

上层功能越多，我越觉得这一点重要。

Agent 可以很聪明，也可以犯很离谱的错。底层权限最好对这两种情况都一样冷淡。

这一组文章从最新版总览开始。授权队列、CommandAccess 和 TUI/WebUI 的交互细节单独写在授权中心：模型可以提权限，但不能替我批准。第一版关于 OAuth、Tunnel、MCP 请求链路和早期 Workspace 实现的记录还在这里。

wcode 里，我把 MCP 和 Skill 分开了

Wed, 26 Aug 2026 03:16:00 +0800

第一版 wcode 基本是围着 MCP 写的。

那时候最核心的问题是：Web 端模型怎么安全访问本地代码。

现在 Software Intelligence、Verification、Reconciliation 都长出来以后，MCP 在项目里的位置反而更简单了。

它就是能力接口。

本地 Agent 没必要绕公网#

如果 Agent 本身就在本机，比如 Claude Code、Codex、Grok Build 这类，没必要为了调用本地仓库先走一圈 Tunnel 和 OAuth。

直接：

wcode --workspace /absolute/path/to/repository mcp-stdio

stdio 和 HTTP 后面没有两套业务实现。

最终用的还是同一个：

Workspace
Harness
Software Intelligence
Verification / Evidence
Tools
Prompts
Resources
Tasks

Transport 不一样，能力边界应该一样。

这件事我比较在意，因为很多工具做到后面会出现“本地模式一套，Remote 模式另一套”，最后修安全问题要修两遍。

Web / Cloud 还是 HTTP + OAuth#

ChatGPT、Grok Web、Claude Web 这类产品从云端访问本机，还是需要公网可达地址。

所以第一版里的 Streamable HTTP、OAuth、PKCE、Resource Binding、Quick Tunnel 都还在。

这些底层细节我在第一版文章写过，这里不展开。

后面主要补的是协议兼容和长任务。

现代 MCP 请求可以声明 Tasks Extension。现在只把确实可能很慢的操作做成 Durable Task，例如：

semantic_provider_refresh
verification_execute_stages

客户端声明 Tasks，就可以拿 Handle 后轮询；不声明，仍然走同步调用。

我不想为了跟最新协议，把还能正常工作的客户端全部逼着一起升级。

Tool 现在也带 Product Scope 信息#

这块是后来才加的。

wcode 自己的能力已经很多，如果 Agent 只看到几十个 Tool Name，很容易把它们理解成一张平面列表。

现在 Product Scope Registry 会同时用于源码分区、software_context、Semantic Scope 和 MCP Tool Metadata。

也就是说，Agent 不只知道有个 risk_status，还可以发现它属于哪些 Product Scope；scope_status 也能直接看当前仓库源码映射和未归类文件。

这不是为了给 Tool 多加标签。

主要是让 Agent 在开始做事之前先知道“我现在在哪个能力边界里”，不要动不动就全仓库搜索。

Skill 不应该偷偷带执行权限#

现在可以导出一个 Agent Plugin / Skill：

wcode --workspace "$PWD" agent-plugin --output wcode-agent-plugin

目录很小：

wcode-agent-plugin/
├── plugin.json
├── .claude-plugin/
│   └── plugin.json
├── README.md
└── skills/
    └── wcode-software-intelligence/
        └── SKILL.md

我故意没往里面塞 Hook、JS/Python Script、Credential，也没把 Workspace 配置偷偷写进去。

我后来把这个边界总结成一句很普通的话：

Skill = workflow
MCP = capability

Skill 可以告诉 Agent 我希望它先做：

workspace_info
scope_status
design_status
project_context
software_context(scopes=...)

修改以后再走 Review、Impact、Risk、Verification。

但 Skill 自己不能因为“装上了”就突然得到 Shell、删除文件或者运行仓库程序的权限。

权限还是 Runtime 的事。

Workspace 我一直要求显式#

持久化 Agent 配置里，我更推荐写绝对路径：

wcode --workspace /absolute/path/to/repository mcp-stdio

而不是让 Plugin 根据当前 cwd 自动猜仓库。

这不是审美问题。

Agent 从子目录启动、Plugin 自己有工作目录、IDE 改了 Project Root，这些情况都很常见。自动向上找父目录一旦找错，影响的是权限边界，不只是路径显示不好看。

所以 Workspace 是 wcode Runtime 的显式参数。

Skill 不替我决定。

授权也不交给 Skill#

现在 wcode 对高风险执行和删除都有本地 Authorization Flow。

例如一个 Language Server Refresh 如果没有预先通过 --allow-risky-exec 放开，可以先产生 Authorization Request；我在 TUI 里批准后，Agent 再重试。

Delete 则是 exact one-shot approval。

这些动作 Skill 都不会自动替我确认。

我觉得这一点很重要：Skill 可以告诉 Agent“遇到授权就说明原因并等待人处理”，但它不能为了让流程顺滑，顺手把信任边界也一起扩大。

换模型这件事因此变得没那么重#

以前我会比较在意某个 Agent 有没有自己独特的 Memory、Rule、Project Context。

现在当然还是会在意模型能力，但项目状态不太想绑在它身上了。

Verification Plan、Evidence、Reconciliation、Graph History、Semantic Registry 这些长期状态都留在 wcode。

一个 Agent 只要能调用 MCP，就能接同一个 Workspace；安装同一份 Skill，只是更容易遵循同一套工作习惯。

从 Claude 换到 Codex，或者 Web 端换成本地 Agent，模型上下文会变，但项目本身不应该跟着清零。

这样换模型时轻松很多，MCP 也没有继续膨胀成一套自己的 Agent。

最后还是会回到最底层的问题：这些 Agent 到底能在我的机器上做什么。Workspace、命令执行和授权的边界，我单独写在我还是不想给 Agent 一个 Shell 里。

wcode 最近做成什么样了

Wed, 26 Aug 2026 03:10:00 +0800

我前几天写过一篇 wcode 的第一版介绍。

那篇写的是最早的 wcode：我想在 Web 端继续用自己喜欢的模型，又想让它们安全地碰到本地代码，所以做了 Remote MCP、OAuth、Workspace、Tree-sitter、文件修改和命令执行。

这些东西现在都还在。

但写完第一版没多久，我发现项目已经不是那篇文章里的样子了。

底层没有推翻，反而越来越像基础设施。后来我反复改的其实是另一件事：一次代码修改结束以后，到底留下了什么。

模型把代码改出来已经不算很难。难的是一个仓库被我、不同模型、不同工具来回改几十次以后，我还能不能回答这些问题：

这段代码为什么必须这样？
它对应哪个需求？
这次修改实际碰到了哪些功能？
原来的约束还成立吗？
测试绿了，绿的是哪个 revision？
谁 review 过？
还有没有没处理完的东西？

Git 很擅长告诉我“哪里变了”，但它不会替我保存“为什么这么设计”。聊天记录更不适合做这个事情，换个模型基本就断了。

所以最近 wcode 的重心慢慢从“给模型一套本地工具”，变成了“把软件本身的状态留下来”。

现在粗略可以画成这样：

.wcode Design State
        │
        ├── Requirement / Constraint / Acceptance
        │
Product Scope ───── Source Code
        │              │
        └──── Software Graph
                    │
               Git Actual State
                    │
          Drift / Impact / Risk
                    │
          Reconciliation Plan
                    │
              Verification
                    │
                Evidence

这张图看起来比第一版复杂不少，但实际使用时反而更简单了：模型还是写代码，wcode 主要负责把它写代码前后那些容易丢掉的状态接起来。

我先把“为什么”放进仓库#

最先加的是 Design State。

现在项目可以有一份 .wcode：

.wcode/
├── project.yaml
└── design/
    ├── product.yaml
    ├── requirements.yaml
    ├── components.yaml
    ├── constraints.yaml
    ├── acceptance.yaml
    └── decisions.yaml

我没有想把它做成另一种编程语言。里面主要是稳定 ID 和关系：Requirement 由哪个 Component 实现，Component 落在哪些代码上，Acceptance 最后由什么测试或检查来验证。

这样我再改 Workspace Security 时，入口不一定非得是“先打开哪个 Rust 文件”。可以先问：这个 Requirement 现在的实现和验证在哪里。

wcode 自己也在用这套 Design State。这个 Dogfood 很重要，因为只设计格式不用，很容易最后做出一堆看起来完整、实际没人愿意维护的 YAML。

仓库大了以后，我又加了 Product Scope#

后来代码继续长，另一个问题出来了。

即使已经有 software_context，一个任务如果每次都在整个仓库里找，返回的东西还是会越来越杂。尤其 wcode 自己同时有 Runtime、MCP、Workspace、Graph、Verification、UI，一句“看看安全问题”很容易把几个完全不同的模块一起捞回来。

所以现在有一套固定的 Product Scope。

它不是业务标签系统，更像 wcode 自己的能力分区。scope_status 会告诉我源码现在落在哪些 Scope，还有哪些文件没有被归类；software_context(scopes=...) 则可以真的把源码导航缩到选中的范围。

这个功能的起因很朴素：我不想项目目录已经拆得很清楚了，Agent 进来以后又把它当成一个巨大的平面文件夹。

Software Graph 还在，但我不再拿一团球当 UI#

Tree-sitter 仍然是底座。

它不需要启动项目，也不需要信任仓库配置，就能拿到定义、Range、Qualified Name 和一部分语法级调用关系。这些关系进入 Software Graph 时会老老实实写：

provider = tree-sitter
precision = syntax

如果本机有对应 Language Server，而且我允许它运行，wcode 才会把真实返回的 Document Symbol、Call Hierarchy、Implementation 作为 semantic fact 加进去。

源码变了以后，旧 LSP 结果会因为 Source Hash 不一致变成 stale，不再混进新的分析。

Graph 也会留 meaningful history，可以看版本之间 Node / Edge 到底怎么变了。

一开始我给 WebUI 做过一个可以拖拽、缩放、筛选的 Graph Canvas。技术上没什么问题，但我自己用几次就觉得没意思。

我打开页面不是为了看一团会动的球。

我想看的是：

这个 Requirement 是什么
谁实现它
现在代码落在哪里
Acceptance 怎么验证
这次 Git 改动碰了什么
设计依赖和代码依赖有没有对上

所以现在主界面已经换成 requirement-first 的 Project Observatory。低层 Software Graph 还在，而且仍然参与 Impact、Context 和历史 Diff，只是不再被当成“产品首页”。

这个改动我自己很喜欢。图是手段，不是目的。

Risk 不再只靠 Prompt 提醒#

以前让 Agent 改安全相关代码时，我经常会顺手补一句：

这个地方比较重要，多检查一下。

现在回头看，这句话几乎没约束力。

wcode 会把 Git Change、Traceability Gap、Drift、Design 里声明的风险以及一些结构性变化合起来，再决定 Verification 要走多深。

最近还补了 Maintainability Review。

例如一个文件这次改动后从 1,000 行以下跨到 1,000 行以上，或者大量代码集中长在一个文件里，或者一次变更横跨多个 Product Scope，review_changes 会把它们作为结构信号提出来。

这不是在声称“超过 1,000 行就一定烂”。它只是提醒：代码在往一个值得单独看一眼的方向长。

Medium 及以上风险的 Verification Plan 还会有独立的 maintainability reviewer。Correctness 过了，不代表结构就可以不看。

Verification 现在会留下证据#

verify_project 还在做最普通的工程检查。

Rust 项目仍然是这些：

quick
  git diff --check
  cargo fmt --check
  cargo check --locked

full
  cargo test --locked
  cargo clippy --locked -- -D warnings
  cargo build --release --locked

更深一层的 Verification Plan 可以要求 Property、Mutation、Fuzz、Runtime Canary、独立 Reviewer 或 Human Approval。

我以前最不喜欢 Agent 最后只留一句：

Tests passed.

现在 Verification 会形成 Evidence，至少能知道是谁产生的、针对哪个 code revision、哪个 design revision、什么 policy、结果是什么。

Reviewer 结论冲突也不会被后来的 Pass 冲掉。冲突就是 Disagree。

“有争议”本身比“系统帮我平均成通过”更有用。

Reconciliation 是我最近改得最多的一块#

早期 Coding Agent 的流程基本是：

读 → 改 → 测 → 结束

现在我更关心“这个修改什么时候真的算结束”。

Reconciliation Plan 会把 Drift、Impact、Risk、Change Intent 和 Verification Requirement 组织成有依赖的任务。执行状态可以 Claim、Submit、Retry，而且会持久化。

所以一个模型做 Implementation，另一个模型来做 Security Review，再换一个补测试，不需要共享同一段聊天历史。

它们面对的是同一个 Plan、同一个 revision、同一组 Evidence。

不过 Reconciliation 没有一套隐藏的超级权限。真正改文件还是走 Workspace 的 Root、SHA、原子写入、Symlink/Hardlink 防护和授权逻辑。

Plan 不能覆盖现实里的文件状态。

有些权限我后来做得更细了#

第一版只有比较粗的 --allow-risky-exec：启动时显式告诉 wcode，这个进程可以跑 repository-aware 的高风险执行。

现在这条路径还在，但不是唯一方式。

Language Server、Runtime Executor 这类操作，如果当前没有进程级授权，也可以先生成一个本地 Authorization Request。我在 TUI 或受保护 WebUI 里批准这个具体操作，再重试。

现在还多了一层 CommandAccess：模型请求一个当前 Workspace 尚未授权的裸可执行程序名时，会自动进入 Pending 列表。TUI 用 ↑/↓ 选择，Y / N 只处理当前选中请求；Project Observatory 也能逐条批准或拒绝，同时管理项目和已授权命令。批准某个 Program 不会开放 Shell，Shell Interpreter、路径逃逸和受保护资源仍是硬边界。

删除更严格：delete_path 只能删普通文件或空目录，文件还要带当前 SHA，而且授权是 exact one-shot，用完就没了。

我更喜欢现在这个粒度。不是为了省一次确认，就把整个进程后面的高风险操作全部放开。

MCP 反而退到了后面#

第一版文章里 MCP 是主角，现在它更像接口层。

本地 Agent 直接走：

wcode --workspace /absolute/path/to/repo mcp-stdio

Web / Cloud 端走 Streamable HTTP + OAuth。

后面还是同一个 Workspace、Harness、Software Intelligence 和 Evidence Runtime。

需要把工作习惯带到不同 Agent 时，可以导出一个很小的 Skill：

wcode --workspace "$PWD" agent-plugin --output wcode-agent-plugin

它只有 Metadata 和 SKILL.md，不会顺手塞 Hook、脚本、Credential，也不会替我猜 Workspace。

Skill 告诉 Agent 怎么工作，MCP 决定它到底能做什么。我还是想把这两件事分开。

现在我怎么用#

平时还是：

wcode --workspace "$PWD"

进入一个不熟的仓库，我现在更习惯先看：

workspace_info
scope_status
design_status
project_context

再根据任务选 Scope，用 software_context 找代码。

改完后才是：

review_changes
→ drift_status / impact_analysis / risk_status
→ reconciliation / verification
→ evidence_status

TUI 里 I 看 Intelligence，W 打开 Project Observatory。

这一套还在继续变，但方向已经和第一版很不一样了。第一版解决“怎么让模型安全地进仓库”，最近这些东西解决的是“它进来以后，项目怎么别越改越说不清楚”。

后面几篇我分开写：

代码在 https://github.com/francis-du/wcode。

我写了 wcode：把 Web AI 接到本地代码库

Sun, 23 Aug 2026 18:30:00 +0800

官网与文档 ↗GitHub ↗

这篇保留的是 wcode 第一版的实现状态，我不会跟着后续代码逐段回写。现在的版本已经继续做了 Design State、Product Scope、Verification、Evidence、Reconciliation 和 Project Observatory，见 wcode 最近做成什么样了。

我平时会同时用几个 AI 的 Web 端。它们的模型和对话体验已经很好了，但一碰到本地项目，事情就变得很别扭：要么手动复制代码，要么换到另一个 Coding Agent，要么再申请 API Key、单独付一份 Token 账单。

但我并不想再造一个 Agent。

模型、上下文管理和 Agent Loop，Web 端都已经有了。我缺的只是一根管子，让它能在我允许的范围内读写本地代码。于是有了 wcode：一个用 Rust 写的 Remote MCP Bridge。

在项目目录里运行一个二进制，它会启动本地 MCP Server、OAuth、HTTPS Tunnel、配置页和终端监控。然后把生成的 /mcp 地址加到 Grok、Claude、ChatGPT、Mistral 或其他支持 Remote MCP 的客户端里，就可以直接聊本地代码。

还有一个很现实的用法：薅 Web 端。

如果一个 Web 产品允许在对话里接入自定义 MCP，那么模型继续用 Web 端提供的能力，代码搜索、读取、修改和验证则由本机的 wcode 完成。这样不需要为了 Code Agent 再配一套模型 API Key，也没有额外的按量 API Token 账单。

这不是绕过平台限制。模型回复仍然受 Web 端自己的套餐、消息数、Credits、速率或上下文规则约束。准确地说，wcode 省掉的是“为了让 AI 访问本地代码，再买一份 API Token”的成本。

wcode 只做桥接#

我一开始就给它定了边界：不负责选模型，不负责实现 Agent Loop，也不保存聊天记录。它只把 MCP 请求转换成受控的本地代码操作。

Web AI / Coding Agent
          │
          │  Remote MCP + OAuth
          ▼
┌──────────────────────────────┐
│            wcode             │
│                              │
│ Auth ─ MCP ─ Tool Harness    │
│                 │            │
│       Code Index / Workspace │
└─────────────────┬────────────┘
                  │
                  ▼
          指定的代码目录

网络层用 Axum 和 Tokio，终端界面用 Ratatui，代码索引用 Tree-sitter。最后编译成一个原生二进制，没有数据库，也没有另外一组常驻服务。

源码里的模块基本就是按照边界拆的：auth.rs 管 OAuth，mcp.rs 管协议和工具路由，workspace.rs 管文件与命令安全，code_index.rs 管语法索引，harness.rs 管并发和项目级工作流，monitor.rs 只记录并展示真实任务。

启动时三个 Axum Router 会合到一起：

let app = auth::router(auth.clone())
    .merge(mcp::router(app_state))
    .merge(control_router);

let server_task = tokio::spawn(async move {
    axum::serve(listener, app).await
});

本地 Server 先启动，公网 Tunnel 后启动。这样即使 Cloudflare DNS 或 TLS 还在预热，本地服务和公网问题也不会搅在一起。

一次 MCP 请求怎么进来#

wcode 的 /mcp 不是拿到 URL 就能调用。一个请求真正进入工具层之前，要依次过四关：

Origin 是否匹配
        ↓
Bearer Token 是否有效，并绑定当前 Resource
        ↓
MCP 协议版本是否支持
        ↓
Header、JSON-RPC method、_meta 是否一致
        ↓
tools/list 或 tools/call

MCP 生态还在快速变化，各个客户端升级并不同步。所以 wcode 里保留了两条路径：新协议走无状态 POST，老客户端仍然可以通过 initialize 握手连接。未知版本会明确报错并返回支持的版本，不会悄悄猜一个版本继续跑。

如果 HTTP 请求里带了 Origin，wcode 会检查 Scheme、Host 和有效端口是否与公开 MCP 地址一致，同时拒绝额外的 Path、Query 和 Fragment。这不是普通的 CORS 装饰，主要是为了降低本地 HTTP Transport 被 DNS Rebinding 利用的风险。

新协议的请求还会交叉检查 Mcp-Method Header 和 JSON-RPC 的 method。调用工具时，Mcp-Name 也必须和 params.name 对得上。协议边界宁愿多拒绝一次，也不应该模糊地接受两个互相矛盾的路由信息。

OAuth 为什么放在本地#

Grok、Claude 这类云端产品访问不到 127.0.0.1，所以 wcode 默认会用 Cloudflare Quick Tunnel 创建临时 HTTPS 地址。但 Tunnel 只解决网络可达性，不负责授权。

第一次访问 /mcp，客户端会得到 401 和 Protected Resource Metadata 地址：

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://…/.well-known/oauth-protected-resource/mcp", scope="mcp"

后面的流程是标准 OAuth 2.1 + PKCE：客户端发现元数据、注册、打开授权页、交换 Authorization Code，最后拿到绑定当前 /mcp Resource 的 Token。

Client          /mcp          OAuth          Browser
  │               │             │               │
  ├─ POST ───────►│             │               │
  │◄─ 401 + metadata ────────────┤               │
  ├──────── register ───────────►│               │
  ├──────── authorize + PKCE ───►├─ pairing ────►│
  ├──────── exchange code ──────►│               │
  │◄──────── access token ───────┤               │
  └─ Bearer + tools/call ───────►│               │

授权页还要输入终端显示的六位验证码。只拿到临时公网 URL 的人，不能直接替你授权。Authorization Code 是单次、短时的，Refresh Token 会轮换，Redirect URI 只接受 HTTPS 或受约束的 Loopback 地址。

MCP 新版更推荐 Client ID Metadata Document，但我没有默认抓取客户端随便给出的 Metadata URL。自动化是多了一点，同时也新开了一个出站网络、SSRF 和 DNS Rebinding 的口子。在没有完整处理这个信任边界之前，我更愿意保留 DCR 兼容路径。

授权面板把项目、命令白名单和精确仓库操作的授权放在本地显式管理，模型不能批准自己的请求：

文件沙箱最麻烦的不是 `../`#

最早写 Workspace 层时，我很快发现：检查一下路径里有没有 ..，离“只能访问这个目录”还差得很远。

每个工作区在启动时都会先 canonicalize。文件系统根目录、Home 目录这类范围过大的 Root 默认拒绝；多个工作区如果是父子关系，也默认拒绝。在 Unix 上，wcode 还会记住 Root 的 Device/Inode。

每次文件操作之前，Root 都要重新解析并核对身份。如果服务启动后，同一路径被换成了另一个目录，即使字符串完全没变，操作也会中止并要求重启。

模型传进来的路径只能是相对路径，除此之外还会拒绝：

..、绝对路径和 Windows Prefix；
含冒号的 Path Component，避免 Alternate Data Streams；
.git、.env*、密钥和常见凭据位置；
路径中的任意 Symlink Component；
Unix 上指向多处的 Hard Link 写入。

已有文件和新文件也不能用同一套解析逻辑。已有文件可以 Canonicalize 到最终目标，再确认它仍在 Root 内；新文件的叶子还不存在，只能先解析父目录，然后确认父目录没有逃出去。

读文件本身也有竞态。wcode 在读取前后各取一次 Metadata，比对长度和修改时间。如果中途变了，这次读取直接失败，让客户端重试。成功返回时会同时带一个 SHA-256，后续编辑必须使用它。

stat before → read → stat after → SHA-256
     │                 │
     └── 不相等就重试 ─┘

防止 AI 用旧上下文覆盖新代码#

假设模型读到了版本 A。在它思考的几秒里，我手动改成了版本 B。模型如果还按 A 去替换文本，很容易把我的改动一起覆盖掉。

wcode 的写入同时用了三层保护：请求携带读取时的 SHA-256；同一个文件的并发写入使用一把进程内锁；真正拿到锁以后，再重新解析路径、读取文件并检查哈希。

写入也不是直接 truncate 原文件。它会在相同目录创建一个 create_new 临时文件，写完 sync_all，继承原权限，再原子替换目标。Unix 走同文件系统的 rename；Windows 使用带 REPLACE_EXISTING 和 WRITE_THROUGH 的系统调用。最后再尽量同步父目录。

创建文件是另一条路径。临时文件会以 Create-new 语义落到目标位置；如果另一个任务恰好先创建了同名文件，这次请求失败，不会覆盖它。

另外我没有给模型 Delete Tool。大幅缩短现有文件也会被当成破坏性写入，除非用户显式开启 --allow-destructive-writes。这不保证 AI 永远不犯错，但能把最难恢复的错误挡在默认路径之外。

Tree-sitter 只承诺语法精度#

如果工具只有全文搜索和 read_file，模型很容易退化成“把整个文件发给我看看”。上下文浪费大，定位也不精确。

wcode 内置 Tree-sitter，提供三个语法级工具：

file_outline：列出定义、签名和准确范围；
find_symbol：跨文件查找定义；
symbol_context：围绕一个符号返回有限正文、嵌套定义和语法调用。

索引是 Lazy 的。只有真正请求某个文件或符号时才解析；目录搜索会先做便宜的文本预过滤，再对候选源码建树。完整 AST Cache 最多保留 128 个文件，目录符号搜索最多扫描 50,000 个源文件。写入成功后，对应的 Symbol Record 和 AST 会立即失效。

这里我刻意没有把结果包装成“语义理解”。所有模型可见的索引结果都写着：

{
  "provider": "tree-sitter",
  "precision": "syntax"
}

它能回答哪里定义了函数、语法上出现了哪些调用，但不假装自己做了宏展开、类型推断、重载选择或动态分派。对 Agent 工具来说，明确能力边界比伪造一个很强的答案更重要。

并发不是越满越好#

wcode 只有一个全局 Tokio Semaphore，所有真实工具任务都从这里拿 Permit。默认上限是逻辑 CPU 数的八倍，并 Clamp 到 64–128；也可以通过 -j 调整，内部硬上限是 256。

一条任务只走这几个状态：

queued → acquire permit → running → completed / failed

parallel_tools、review_changes 和 verify_project 这类组合工具有个容易踩的坑：父任务不能先占一个 Permit，再等子任务。否则当 -j 1 时，父任务拿走唯一槽位，子任务永远跑不起来。

所以组合工具本身不占父 Permit，每个真正做事的 Child 自己排队。parallel_tools 只允许 Read/Discovery 操作，最多 128 个子任务；单个结果最多 512 KiB，总响应最多 8 MiB。

另一方面，能一次遍历做完的工作没有必要强行并行。search_many 和 read_files 会优先做批量操作，减少 MCP Round Trip。互相依赖的编辑保持串行，Cargo Test、Clippy、Build 这类重任务也分阶段执行，避免一起争抢编译缓存。

TUI 里的 Slots 和 Peak 就来自这些真实 Permit，不是 UI 模拟出来的繁忙程度。

我不想给模型一个远程 Shell#

run_command 接收的是 Program 和 Argument Array，从来不经过 Shell。默认允许面很窄：受限制的 Git/ripgrep 只读操作，以及形状完全匹配的 cargo fmt --check、cargo check、cargo check --locked。

Git Mutation 始终阻止。子进程的 GIT_* 状态会被清理，交互式 Prompt、Helper、外部 Diff 以及能改变仓库发现范围的配置也会被拒绝。stdout/stderr 有上限，执行有 Timeout，敏感环境变量不会传进去。

为什么连 Build 和 Test 也不默认放开？因为 Cargo Build Script、Proc Macro、Makefile、Package Script 和测试代码都由仓库控制。“这是一个测试命令”不代表它安全。

项目级验证走 verify_project。Harness 会先识别 Cargo、Go、Node、Flutter、Make 等项目，再根据 Manifest 和仓库规则推导检查命令。只有通过 Exact-shape Validation 的命令，才会临时进入验证通道。便宜的检查可以重叠，编译重任务按阶段跑，返回给模型的诊断只保留有界尾部。

--allow-risky-exec 可以放宽命令策略，但它是一次明确的信任扩张，不是 OS Sandbox。我不希望为了让 Demo 看起来“什么都能跑”，把这个 Flag 默认打开。

Harness 不是一句 Prompt#

这里单独说一下 Harness，因为它不是在 System Prompt 里写一句“改完记得跑测试”。它是一层有状态、可执行、带边界的工程工作流。

模型第一次进入仓库，应该先调用 project_context。Harness 会查看根目录里的 Manifest 和 Lockfile，识别 Rust、Node、Python、Go、Make 等项目类型；同时按固定优先级读取 AGENTS.md、CLAUDE.md、README.md 一类仓库说明。每个文件有行数和字符上限，所有说明还有总字符预算，内容仍然经过 Workspace 的敏感信息脱敏。

识别结果会生成一个 ProjectProfile，里面包括项目类型、Manifest、仓库规则、推荐检查和默认工作流。例如发现 Cargo.toml 时，会推导：

quick: git diff --check
quick: cargo fmt --check
quick: cargo check --locked

full:  cargo test --locked
full:  cargo clippy --locked -- -D warnings
full:  cargo build --release --locked

如果存在 package.json，Harness 只读取实际存在的 lint、typecheck、check、format:check、test、build Script，并根据 Lockfile 选择 npm、pnpm、yarn 或 bun。Makefile 也只识别明确存在的 check、lint、test Target，不凭空猜命令。

Project Profile 会缓存，但不是永远不变。Fingerprint 来自 Manifest 和 Guidance 的 Metadata；这些文件变化后，下次请求会重新构建。构建发生在 Cache Lock 外面，避免一个大仓库的上下文发现阻塞其他 Workspace。写回缓存前再检查一次，解决并发请求重复构建时的竞态。

review_changes 也没有直接返回整份 Git Diff。它并行跑五个只读 Probe：

git status
unstaged numstat     staged numstat
unstaged diff-check  staged diff-check

Harness 把结果合并成文件列表、增删行数和风险分类。改了源码却没改测试、动了认证或 Token 文件、改了 Manifest、删了测试、碰了 Migration/Workflow，都会产生对应 Finding。变更超过 25 个文件或约 1,000 行会提示拆分；风险再高一些时，会直接推荐 Full Verification。这里最多分析 500 个文件、保留 64 条 Finding，避免一个巨大 Working Tree 把上下文打爆。

这些分析结果在 WebUI 里可以直接看到：当前变更、每个文件命中的 Requirement、代码统计和风险等级：

verify_project 接受 quick 或 full。它先把推导出的检查排序，再按 Phase 执行：

Phase 0  format / static check / diff check
   ↓ barrier
Phase 1  tests
   ↓ barrier
Phase 2  clippy
   ↓ barrier
Phase 3  release build

同一个 Phase 内彼此独立的检查可以并发，不同 Phase 之间有 Barrier。这样既不把所有命令串行到底，也不会让 Test、Clippy 和 Release Build 同时争 Cargo Cache。每个检查仍然单独获取全局 Semaphore Permit，单独进入 Monitor，并返回 Exit Code、耗时与截断后的 stdout/stderr 尾部。

最关键的是，verify_project 不能借“自动验证”绕过命令策略。推导出的 Program 和 Args 还要经过内部 Exact-shape Validator，只临时放行这一条已经识别的命令，再委托给同一个 Workspace Command Policy。Harness 提供的是一条更容易走对的路，不是第二个后门。

需求详情页把 Desired State → Actual State → Change → Proof → Convergence 排成一条链，验证证据挂在 Proof 一环：

Tunnel 挂了以后怎么办#

每个 wcode 进程都有一个随机 instance_id。cloudflared 输出公网 URL 后，wcode 不会立刻显示 Ready，而是从公网请求 /healthz。只有响应里的 ok 为真，并且 instance_id 与当前进程一致，才会打开 Setup Hub。

这个检查主要防两个问题：Tunnel 的 DNS/TLS 还没准备好；或者同一台机器上的另一个 wcode 实例恰好能响应，造成假就绪。

运行期间每 25 秒检查一次公网状态。连续失败三次，或者发现自己启动的 cloudflared 子进程退出，就把整个 Runtime 当成恢复边界：先恢复终端，再停健康任务和本地 Server，Kill 并 Wait 子进程，最后用原参数重新启动。

Quick Tunnel 重启后 URL 可能会变，所以 wcode 不会假装旧 OAuth 状态还能继续用。需要稳定地址时，应该配置自己的 Reverse Proxy，再通过 --public-url 交给 wcode。

wcode restart 和 wcode stop 复用了同一条 Graceful Shutdown 路径。控制接口有一枚 256-bit 本地随机 Token，保存在权限为 0600 的 Runtime File 中，并做 Constant-time Compare。因为这条 Route 也可能被公网反向代理带出去，所以“它只在本机用”不能成为免认证的理由。

TUI 展示的都是真实状态#

Ratatui 面板里有本地服务、公网 Tunnel、OAuth、MCP 最近活动、工作区任务、队列、Slots、Peak 和吞吐量。

这些数据来自同一个 TaskTicket 生命周期：收到请求时入队，拿到 Permit 时运行，返回时完成或失败。如果异步任务异常 Drop，Ticket 也会结束记录，不会在面板上永久留下一个 Running。

交互式终端使用 Alternate Screen 和 Raw Mode，并通过 RAII Guard 恢复鼠标捕获、光标和主屏幕。忙时大约 150 ms 刷新一次，闲时降到 500 ms。stdout 不是 TTY 或传入 --no-monitor 时，就退化成普通日志。

我不喜欢一些 Agent 产品为了显得很忙，凭空画出一堆并行任务。wcode 的原则很简单：没有发生的事，不显示。

WebUI 侧遵循同一个原则。Project Observatory 把期望架构、实际依赖、漂移、证据与实现覆盖率放在同一个视图里：

完整页面从架构总览、需求详情、当前变更、代码统计到图快照历史，一图到底：

怎么用#

macOS 和 Linux：

curl -fsSL https://raw.githubusercontent.com/francis-du/wcode/main/install.sh | sh

Windows 有 PowerShell 安装脚本，也可以在源码目录直接构建：

cargo install --path .

进入项目目录后运行：

wcode --workspace "$PWD"

要同时开放多个仓库，就重复 --workspace：

wcode \
  --workspace ~/Code/backend \
  --workspace ~/Code/frontend

启动后，在 AI 客户端中添加终端显示的 https://…/mcp，选择 OAuth，再在授权页输入六位配对码。

只想读代码可以加 --read-only；不允许执行命令可以加 --no-exec；已经有固定反向代理，就使用 --public-url https://your-domain.example。

还没解决的东西#

wcode 现在已经能稳定完成我最初想做的事，但它当然不是终点。

Quick Tunnel 适合零配置，不适合需要固定地址的长期部署；Tree-sitter 是跨语言的语法索引，不是 Language Server；不同 Web 产品对 Remote MCP 和 OAuth Discovery 的支持也一直在变化。即使一个客户端声称支持 Streamable HTTP，也不代表它已经能完整跑通 OAuth。

接下来我会继续补客户端实测、协议兼容、代码索引精度、诊断和安全回归。至于模型和 Agent Loop，我还是不打算做。让 wcode 保持一座小而清楚的桥，比长成另一套平台更有价值。

代码留在本地，AI 客户端自己选。