Communitygithub.com

Xylem

将仓库从架构映射到命名函数和关键决策,追踪作用域内的用户旅程,对照源码检查映射,并构建交互式静态站点(探索、旅程、状态图、代码)。适用于有人要求可视化、映射、解释或审计仓库的架构、流程、用户体验路径或代码路径,或想要“整个应用在一页上”时使用。

Xylem 是什么?

Xylem 是一个 AI 智能体技能,旨在将整个代码仓库转化为一个基于源码的、交互式的、多视图映射。它通过一系列确定性的阶段工作,从代码普查开始,逐步构建架构图、用户旅程和函数级细节图。该技能的核心原则是“证据优先”,要求映射中的每个组件、连接或决策都必须有明确的源码位置引用,并在无法确定时诚实标记为“不可用”。最终,它会生成一个包含四个视图的静态网站:探索(系统组件和连接)、客户旅程(带动画的架构流程)、状态图(状态维度与转换)和代码(函数级视图,包括决策和调用轨迹)。Xylem 支持大型仓库,允许分阶段并行处理,并通过严格的验证和交叉审查流程确保输出的准确性,是理解和审计复杂系统的强大工具。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Iineman2/xylem/tree/HEAD/skills/xylem

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

Xylem 是做什么的?

你将把一个仓库转化为一个基于源码的映射。它以静态的双文件站点(index.html 和 deep-view.json)的形式提供四个视图:

视图展示内容
探索组件(系统的组成部分)以及它们之间的连接,按层级分组
客户旅程用户可采取的每个旅程,在架构上以动画展示:请求、回复和标记的交接
状态图映射范围内声明的每个状态维度、它的状态,以及旅程实际经历的转换
代码每个映射到的函数作为其区域中的一个磁贴,包含其决策、调用和被调用者,以及在函数级别追踪的旅程路径

方法比页面更重要。每个声明都必须关联 文件:行号。每个连接都必须是真实的。当代码无法确定某些内容时,映射应如实说明,而不是猜测。

基本原则(在每个阶段都适用)

  1. 无证据,不记录。 每个组件、单元、决策、边、状态和动作都应引用 文件:行号。如果无法引用,标记为 UNVERIFIED 或将其省略。这是作者/审阅者的义务:自动化门禁强制执行架构证据和深度源码位置,而不是每个状态/动作的引用或解释的含义。
  2. 分配 ID;绝不发明实体或连接。 使用脚手架基于文件位置的 ID;手动编写的 ID 也必须是唯一且稳定的。跨区域的边必须依赖已声明的架构连接。如果缺少某个连接,记录一个 diagram_gap,并在代码中验证它之后再添加,并附上证据。
  3. 诚实的缺口优于不可能存在的路径。 如果旅程的结果无法根据源码明确追踪,写入 {"unavailable": "<具体原因>"}。绝不要将成功路径复制到失败结果中。绝不要链接无法同时成立的分支。
  4. 如实说明。 轨迹是 静态源码路径,不是真实运行的记录。在页面中这样标记它们。
  5. 只读。 永远不要编辑目标仓库。将所有内容写入 .xylem/(或用户命名的文件夹)。
  6. 隐私。 除非用户要求,否则不要将仓库内容发送到任何外部服务。该站点仅对其数据和可选的视频进行同源请求。它不发起任何外部请求;在回环地址上提供本地服务以供离线使用。

输出布局

.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:函数级映射(最终解析)

  1. 从普查结果生成草稿映射:
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 标签仅用于直接实现已知缺陷的决策。
  1. 写入 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。该页面不使用任何框架或外部请求。

相关技能