Agent 实践

archify：从仓库证据到可携带的交互式架构图

4 分钟阅读AI可视化跨Agent学习笔记
文章目录
  1. 一句话定性
  2. 它怎么转
  3. 不同图与不同视角
  4. 架构变化怎么比较
  5. 交付与兼容边界
  6. 更新提醒与网络
  7. 许可与场景迁移
  8. 我的判断

原研究日期：2026-10-09；资料核对：2026-10-13。项目：tt-a1i/archify。 本次阅读官方说明与许可证，没有运行生成器、浏览器交互或跨 Agent 兼容性测试。

仓库证据通过引用线组织为可携带的架构关系图
图 1：架构图先有证据，再有视觉表达。

一句话定性

archify 是把仓库证据或有边界的文字描述，组织成类型化关系图，再交付交互式 HTML 的工具。 像一张带注释的地图：标出节点、路径和来源，方便读者追踪；但地图画得清楚，不代表输入的每条路线都被独立测量过。

“truth before spectacle”是PRODUCT.md的设计原则，不是“AI 永不编造”的效果证明。作者提供的事实也可能有误，架构图仍需要与原仓库和实际系统对照。

原稿的 Trending #1、star、安装量、仓库大小和作者资料不能证明产品可靠性；没有本次可复查的历史快照，移除这些排名与质量推论。仓库体积也不是代码行数，赞助方展示不等于持续资金或安全背书。

它怎么转

作者事实或仓库证据先组织成类型化图，再验证并输出独立 HTML
图 2：自包含的是查看产物；关系和来源仍需逐一验证。
  1. 定范围：选仓库证据、限定描述或两个架构快照，不把未知内容补成事实。
  2. 组织类型化源：写清节点、关系、来源和观察范围。
  3. 渲染与检查：将结构交给工具生成查看产物，修复 schema、布局或交付检查发现的问题。
  4. 复核来源：人检查关系是否忠实于代码与描述，再决定是否分享。

结构校验和渲染成功可以验证特定契约，不能认证自然语言事实或完整系统行为。源码里没有执行到的动态路径、运行时配置和外部依赖，尤其不能只凭静态图推断。

不同图与不同视角

当前文档提供架构、工作流、序列、数据流、生命周期等配方，也有 Architecture Delta。它们回答不同问题；数字图表和仪表盘不在该产品主要范围，不能因此贬低 Mermaid 或其他绘图库的用途。

Route 高亮选定路径，Reach 展示上下游可达范围，两者都不能冒充完整架构
图 3：路径与可达范围是不同视角，分享图要写清范围。

Route 展示选定路径，Reach 展示特定起点的上游或下游可达范围。分享卡要保留所选范围，不能把局部截图包装成全系统架构。可达关系来自所提供的图，不自动证明真实运行时确实走过这条路径。

“渐进披露”“有限动效”“品牌不替换语义”值得借鉴，但这些是产品规则，不能直接推出没有可访问性问题、没有语义漂移或所有导出都正确。

架构变化怎么比较

Before 与 After 的同口径快照比较生成 Delta 和机器可读收据
图 4：架构变化来自同口径快照，不是靠视觉动效推测。

Before/After 需要同口径的源、标识与范围，才能讨论 Delta。机器可读收据记录检查结果，不是自动证明变化来自哪个团队、真实部署已经完成或变更完全安全。

官方示例有：

node archify/bin/archify.mjs compare architecture base.json head.json architecture-delta.html --json

这要求相应源码目录、依赖和符合 schema 的输入文件，不是复制到任意安装目录都能运行的承诺。本次仅核对说明，没有执行命令；复现时应记录提交、输入和输出。

交付前逐项问：来源文件是否仍存在，关系是明示还是推断，遗漏组件是否改变理解，快照是否属于同一环境。对推断标明不确定性；对未观察到的路径，不写成“路径不存在”。保留检查失败和修复记录，比只展示一张漂亮的最终截图更有复用价值。

交付与兼容边界

README描述独立 HTML 查看产物：接收者不必安装 Archify 即可查看该文件包含的节点和路径交互。无需托管运行时，不等于任何环境都完全离线；外部网站、地图链接及运行 Agent 时的模型调用仍可能联网。分享 HTML 前还要检查仓库路径、内部链接和敏感信息。

官方列出多种 Agent 入口，但不是“六个平台无条件通吃”。Skill 说明、CLI 执行权限、Node 版本和宿主接口要匹配。Hermes 与 DeepSeek Harness 入口标为社区/可选集成，不能写成 Nous 或 DeepSeek 官方产品；不同入口的 Node 条件也不完全相同。

README 核对时列出 v3.0.1 为稳定版本，不应写成“任何任务都必须用这个版本”。已有工作流应按兼容要求与升级说明选择，不把某个历史版本写成永久要求。

更新提醒与网络

README 说明可选更新检查会访问固定 manifest，只提醒而不自动下载、安装；服务端仍会看到正常 HTTP 元数据。开关 ARCHIFY_UPDATE_CHECK_DISABLED=1 针对该检查及其提醒状态写入，不等于关闭浏览器、Agent 或所有插件的网络。

这是读取到的项目契约，不是抓包审计结论。来源与项目输入应按实际后端检查，不能将“无遥测”推导成全链路零出站。

许可与场景迁移

组件 LICENSE为 MIT；使用或分发需保留相应声明，第三方通知、素材、品牌标识和输入材料权利仍要分别检查。官方免费源码与第三方托管、安装服务或课程不是同一个授权关系。

可以迁移到技术复盘、培训课程、合同流程或旅行安排的关系表达；但合同结论须回到原条款和适用规则，旅行地点与路线须另核实时信息。图形 schema 和免责声明都不能替代专业判断或事实核查。

原稿跨十个项目的热度与道德排行榜，以及对其他 fork 的“盗版”定性，与本篇机制分析无关，且缺乏充分证据，本次移除。不同项目的商业形态和作者背景不适合被压成一张“唯一最好”的表。

我的判断

最有复用价值的是：保留可编辑源、明确图的范围、把局部分享与完整产物分开，并让视觉效果服务可追踪关系。这些设计值得研究；项目是否适合团队，还要看实测、维护和交付要求，不由赞助商或排名决定。

一句话总结：可携带的是图与它记录的来源，不是免于复核的真相。

记录到这里，判断留给实践。