Xylem 是做什么的?
你将把一个仓库转化为一个基于源码的映射。它以静态的双文件站点(index.html 和 deep-view.json)的形式提供四个视图:
| 视图 | 展示内容 |
|---|---|
| 探索 | 组件(系统的组成部分)以及它们之间的连接,按层级分组 |
| 客户旅程 | 用户可采取的每个旅程,在架构上以动画展示:请求、回复和标记的交接 |
| 状态图 | 映射范围内声明的每个状态维度、它的状态,以及旅程实际经历的转换 |
| 代码 | 每个映射到的函数作为其区域中的一个磁贴,包含其决策、调用和被调用者,以及在函数级别追踪的旅程路径 |
方法比页面更重要。每个声明都必须关联 文件:行号。每个连接都必须是真实的。当代码无法确定某些内容时,映射应如实说明,而不是猜测。
基本原则(在每个阶段都适用)
- 无证据,不记录。 每个组件、单元、决策、边、状态和动作都应引用
文件:行号。如果无法引用,标记为UNVERIFIED或将其省略。这是作者/审阅者的义务:自动化门禁强制执行架构证据和深度源码位置,而不是每个状态/动作的引用或解释的含义。 - 分配 ID;绝不发明实体或连接。 使用脚手架基于文件位置的 ID;手动编写的 ID 也必须是唯一且稳定的。跨区域的边必须依赖已声明的架构连接。如果缺少某个连接,记录一个
diagram_gap,并在代码中验证它之后再添加,并附上证据。 - 诚实的缺口优于不可能存在的路径。 如果旅程的结果无法根据源码明确追踪,写入
{"unavailable": "<具体原因>"}。绝不要将成功路径复制到失败结果中。绝不要链接无法同时成立的分支。 - 如实说明。 轨迹是 静态源码路径,不是真实运行的记录。在页面中这样标记它们。
- 只读。 永远不要编辑目标仓库。将所有内容写入
.xylem/(或用户命名的文件夹)。 - 隐私。 除非用户要求,否则不要将仓库内容发送到任何外部服务。该站点仅对其数据和可选的视频进行同源请求。它不发起任何外部请求;在回环地址上提供本地服务以供离线使用。
输出布局
.xylem/
census.json # 在代码中找到的每个定义 (scripts/census.py)
architecture.json # 阶段 1
journeys.json # 阶段 2
deep.json # 阶段 3(函数级映射)
validation.json # scripts/validate.py 的输出
reviews/ # 交叉审查报告(阶段 6)
site/ # index.html + deep-view.json (+ videos/) (scripts/build_site.py)
每个文件的格式在 references/schemas.md 中定义。在写入任何 JSON 之前请阅读它。
阶段和门禁
按顺序执行阶段。每个阶段以门禁结束。除非门禁通过,或者用户接受了有记录的缺口,否则不要继续。在明确授权的试验中,保留失败的工件和日志不变,仅在该试验范围内继续;将后续输出标记为临时性的。结构性的通过并不代表完整的语义覆盖。
阶段 0:代码普查(确定性)
python scripts/census.py <repo> --out .xylem/census.json [--exclude dir ...]
这会使用 Python AST、标准库的 JS/TS 令牌遍历器,以及针对其他支持语言的大致正则表达式,来盘点已命名的定义。scannedFiles 包含零定义源文件。JS/TS 覆盖了通用箭头函数、具体多行/计算属性方法、重载签名、词法函数/类所有者、正则表达式字面量和模板插值;匿名回调不作为普查单元。这是一个有测量的盘点,而非对所有语言语法的证明。在声称完整性之前,请使用独立的解析器或源代码样本对其进行限定。后续的百分比仅描述此盘点结果。
门禁: 普查计数看起来与仓库大小相符。排除的路径是合理的,例如生成的代码或 node_modules。
阶段 1:架构
读取入口点、构建文件、主要模块和进程边界。然后写入 architecture.json:
- 层级: 例如 shell, UI, server, domain, storage, workers, external;
- 组件: 每个包含
id,layer,files[], 一个清晰的职责描述,以及processType; - 连接: 每个
{from, to, label, kind},其中kind为 spawn, ipc, http, file, data 或 uses; - 流程: 主要的端到端流程,作为有序的组件步骤。
门禁: python scripts/validate.py .xylem --only architecture 通过。每个 scannedFiles 条目都属于某个组件,或者有一个合理的 architecture.meta.fileExclusions 条目。证据路径和行必须在证据根目录下存在。
阶段 2:旅程和状态
写入 journeys.json。从 UI、路由、CLI 命令、作业和错误路径中推断出这些内容:
- 状态维度: 每个独立的状态机;
- 屏幕: 每个屏幕;
- 动作: 每个用户动作和系统转换,及其结果、用户看到的确切文本以及撤销操作;
- 旅程: 起始状态加步骤。
每个动作都带有一个有序的架构追踪(交替出现的组件和连接)。返回路径使用 {"connection": [a, b], "direction": "reply"}。当下一步并非从上一步结束的地方开始时,该步骤需携带 transition.handoff,并包含类型和标签:user, timer, queue, continuation, lifecycle 或 download。涵盖快乐路径、不快乐路径、恢复路径和边缘路径。
门禁: validate.py --only journeys 通过:
- 每个旅程都能通过有效的结果重放;
- 零静默跳跃(每次高亮都由一条连线、一个回复或一个带标签的交接到达);
- 没有孤立状态。
阶段 3:函数级映射(最终解析)
- 从普查结果生成草稿映射:
python scripts/scaffold_deep.py .xylem
它会写入 deep.json。草稿包含已分配的普查单元、来自 AST 的 Python 决策,以及启发式的 JS/TS if、while、for、switch 和带括号的 catch 点。JS/TS 不声称完全盘点了三元表达式、计算或短路决策。注释、字面量内容和子声明被排除在每个主体之外。泛型调用保留不同的调用点位置。调用边使用 source: heuristic 和 confidence: name-resolved;未解析的名称不会被发明为链接。根据源码进行细化;名称解析并非类型解析。
2. 通过阅读代码来细化草稿:
- 每个单元的业务可读
summary,根据主体编写,而不是名称; - 对于每个决策,一个
plain问题(例如,“此文件是否大于 16 MiB?”)加上确切的代码test,一个kind(branch, calculation, loop 或 unconditional),以及正确的后继。return或raise结束路径。try 块的正常和错误延续是分开的,而待处理的异常会执行finally然后传播。当不确定时,将后继标记为unresolved;绝不要标记为verified; risk标签仅用于直接实现已知缺陷的决策。
- 写入
actionTraces:对于每个旅程动作和结果,有序的执行事件{component, unit, event, decision?, line, note?, callsite?, returnTo?, precondition?, boundary?}。event是 call, return, branch, async, spawn, ipc, http, file, render, unknown, throw, finally 或 resume 之一。有关激活框架、终端事件和支持的重放限制,请参阅 schemas。- 从真正的发起者开始,例如 UI 处理程序、路由或作业。
- 跟踪调用、返回和进程边界。拒绝必须遵循真正的错误路径返回给用户。绝不能继续执行到“已保存”或“成功”。
- 当路径不可知时,发出
{"event": "unknown", "note": "..."},或将整个结果标记为不可用。
大型仓库:按代码区域将阶段 3 拆分给多个智能体,每个智能体使用相同格式写入 deep-<part>.json,然后使用 scripts/merge_deep.py 合并它们。通过文件和定义行来协调 ID,绝不能通过名称相似性。
门禁: validate.py 通过完整集合:
- 每个普查定义要么已包含,要么明确排除并附有理由;已包含的覆盖率和排除统计是独立的计数器;
- 每条边的端点都能解析;
- 每条跨区域边都依赖于一个连接;
- 决策的后继都能解析;
- 追踪引用都有效;
- 选择器一致性: 对于未更改的值,没有激活帧会做出互斥的选择。源码写入可以更改值;仅凭迭代标签无法重置约束。支持的语法和限制在 schema 中。例如,先
x==='a'为真,然后x==='b'为真,或者一个值被排除后又通过includes()被要求。修复追踪,或将其撤回至unavailable,并说明冲突。
阶段 4:构建页面
python scripts/build_site.py .xylem
这会写入 site/index.html 和 site/deep-view.json。视频是可选的:先将 videos/<journeyId>.mp4 加上 videos/manifest.json 放入 .xylem/ 中(参见 schemas)。通过 HTTP 提供 site/ 目录以进行查看,例如 python -m http.server -d .xylem/site。file:// 页面无法加载代码视图的数据。
门禁: 打开页面并检查每种模式一次:
- 没有控制台错误;
- 手机宽度(420 像素)下没有水平滚动条;
- 键盘和暗色模式正常工作。
阶段 5:可选的真实屏幕录制
如果应用有可以在本地运行的 UI,可以使用 Playwright 录制旅程。起点是 scripts/record_journey.example.mjs。录制规则:
- 驱动真实的 UI,不模拟任何响应;
- 为每一步添加标题;
- 加速空闲等待,并说明加速情况;
- 在
manifest.json中记录每一步的atSec; - 将部分录制标记为“部分”。
查看器会将视频与映射同步,因此视频成为时钟。
阶段 6:交叉审查委员会
尽可能使用两个独立的审阅者:两个不同的模型或智能体,或者至少是一个没有访问作者推理过程的全新上下文。遵循 references/protocol.md:
- 作者永远不给自己评分;
- 审阅者接收文件和代码,绝不接收作者的结论;
- 审阅者运行独立的检查器,并对照源码抽查声明:遵循 protocol.md 中的单一抽样规则(低于其最小值的所有可用项目);
- 调查结果写入
reviews/<reviewer>-<round>.md,包含严重性、证据和具体的修复建议; - 接受门禁: 对架构、旅程、深度、页面/数据以及冻结的包给出明确的 ACCEPT、REJECT 或 BLOCKED。仅 实质性 缺陷才足以证明 REJECT 是合理的:错误的结论、不可能存在的路径,或核心任务被阻止。已声明的限制、诚实的
unavailable标记以及轨迹的静态性不构成拒绝的理由; - 使用有限的审查预算;如果无法解决,则在达到 REJECT/BLOCKED 并保留证据时停止。重新审阅确切的已构建工件,而不是其描述。
门禁: 冻结包的所有工件都通过独立审查接受。从未为了满足抽样配额而编造路径。
阶段 7:发布和报告
告知用户页面中的内容,包含真实计数:
- 函数、决策、旅程和已追踪的结果;
- 有多少结果不可用,以及原因;
- 哪些内容经过了交叉审查。
如实报告限制。
脚本
| 脚本 | 用途 |
|---|---|
census.py | 多语言定义普查(覆盖率分母) |
scaffold_deep.py | 从普查和架构生成函数级映射草稿 |
merge_deep.py | 合并部分映射;通过文件和行协调 ID |
validate.py | 每个门禁:模式、引用、覆盖率、静默跳跃、后继、选择器一致性 |
build_site.py | 导出紧凑的代码视图数据并构建单页站点 |
record_journey.example.mjs | 用于真实屏幕旅程视频的 Playwright 起点脚本 |
Python 脚本需要 Python 3.9+,并且仅使用标准库。可选的 .mjs 浏览器/录制辅助工具需要单独可用的 Playwright。该页面不使用任何框架或外部请求。