软件工程地图：从代码可视化到统一工程知识模型

/research/software-engineering-map.md

软件项目的可视化，不应被理解为“把代码画成图”。真正有价值的方向，是把一个项目从只能被逐行阅读的代码文本，转化为可以被导航、查询、解释和推演的工程地图。它的目标不是替代代码，也不是让人远离技术细节，而是让不同角色能按自己的问题进入系统：产品看功能，开发看实现，维护者看故障路径，架构负责人看边界和演进风险。

这件事的难点在于：软件工程里有很多图。功能图、架构图、时序图、数据流图、状态机图、依赖图、部署图、影响分析图，各自回答的问题都不同。如果只是把它们并列摆出来，最后会变成一堆互不相干的静态文档；如果强行合成一张大图，又会变成不可读的架构毛线球。

真正的统一方式，不是把所有图压成一种图，而是建立一套统一的底层工程模型：底层用工程知识图谱承载项目事实，上层用不同视图回答不同问题。换句话说，图不是源头，图只是投影；工程对象和关系才是源头。

一、代码可视化的本质不是画图，而是建立工程地图

传统代码理解通常从文件和函数出发：先看目录，再看入口，再顺着调用读代码，最后在脑子里拼出系统结构。这种方式的问题是，系统结构、业务意图、数据流向、状态变化和扩展边界都隐含在代码背后，需要依赖经验慢慢还原。

工程地图的方向正好相反：先把系统中的功能、入口、流程、模块、数据、状态、事件、测试、部署和故障线索显性化，再允许用户从任何一个点下钻到代码细节。它将理解路径从“代码细节 → 猜出系统结构”反转为“系统结构 → 定位代码细节”。

这套系统最少要回答三类问题：

1. 理解类问题：这个系统提供什么能力？整体如何组织？一个功能是怎么跑起来的？
2. 诊断类问题：某个问题出现时，应该沿着哪些路径定位？可能涉及哪些接口、服务、数据和日志？
3. 演进类问题：如果要新增、修改或删除一个功能，应该动哪里？会影响哪些模块、数据结构、测试和外部依赖？

如果一套可视化系统不能帮助完成这三件事，它就只是漂亮文档；如果能帮助完成这三件事，即使第一版图不多，也已经具有工程价值。

二、不同类型的图为什么不能简单合并

不同工程图的目的天然不同。功能图关注系统能做什么，架构图关注系统由哪些部分组成，时序图关注一次调用如何发生，数据流图关注数据如何流动，状态机图关注对象生命周期，依赖图关注谁依赖谁，部署图关注服务运行在哪里，影响分析图关注改动会波及哪里。

这些图之间并不存在简单的父子关系。它们不是同一个维度上的不同层级，而是从不同问题出发，对同一个系统进行观察。功能图偏业务理解，时序图偏运行行为，数据图偏信息流动，状态机偏生命周期，依赖图偏结构耦合，影响图偏变更风险。

所以，统一它们的方式不是寻找一种“万能图”。万能图不存在。一张图如果试图同时表达所有信息，只会同时失去所有用途。正确做法是保留不同视图的差异，同时保证这些视图背后引用的是同一批工程对象、关系和证据。

三、统一的关键：工程知识图谱

真正的底座应该是一套工程知识图谱。图谱里不是抽象地保存“线条和方框”，而是保存软件项目中的真实工程对象，以及它们之间的关系。

典型工程对象包括：

• 业务能力 Capability
• 功能 Feature
• 用户角色 Actor
• 页面、命令、API、定时任务等入口 Entry Point
• 服务 Service
• 模块 Module
• 函数 Function
• 数据实体 Entity
• 数据库表 Table
• 事件 Event
• 状态 State
• 配置 Config
• 外部依赖 Dependency
• 测试 Test
• 日志 Log
• 故障 Issue
• 需求 Requirement
• 部署单元 Deployment Unit
• 架构决策 Decision

这些对象之间可以建立稳定关系：

• Capability 包含 Feature
• Feature 通过页面、API、命令或任务暴露
• API 调用 Service
• Service 使用 Module 或 Repository
• Module 调用 Function
• Function 读写 Entity 或 Table
• Entity 产生 Event
• Event 触发 Job 或外部调用
• Test 覆盖 Feature、API 或 Module
• Issue 关联 Log、API、Service、Table 或代码位置
• Requirement 影响 Capability、Feature、API 和数据模型
• Decision 解释某个边界、依赖或技术选择为什么存在

一旦底层有了这样的对象模型，不同类型的图就不再是彼此孤立的图片，而是同一个工程知识图谱的不同投影。

四、每个节点都必须带证据

工程知识图谱最容易失控的地方，是把“猜测”和“事实”混在一起。真正可用的工程地图，不能只说“这里大概是订单模块”“这个服务可能负责通知”，而要能追溯到证据。

每个节点和关系都应该至少带四类元数据：

对象：TaskService.create
类型：Service Method
证据：src/task/service.py:42-96
来源：静态分析 / 测试扫描 / 运行时 trace / 人工标注 / AI 总结
置信度：high / medium / low
更新时间：2026-06-21

这样做有三个好处。

第一，用户能从图跳回代码，不会停留在概念层。第二，AI 生成的解释可以被审计，不会变成幻觉文档。第三，当代码变化后，系统可以知道哪些关系需要重新验证，哪些视图可能已经过期。

所以，工程地图的基本单位不应该只是“节点”和“边”，而应该是：

工程对象 + 关系 + 证据 + 来源 + 置信度 + 更新时间

没有证据的图，只能辅助讨论；有证据的图，才可能进入维护流程。

五、同源数据，多视图投影

以“登录功能”为例，底层图谱里可能存在这样一条链路：

登录功能
→ 登录页面
→ POST /api/login
→ AuthController
→ AuthService
→ UserRepository
→ users 表
→ SessionToken
→ Redis
→ login_success 事件

从这条链路可以投影出多种视图。

功能视图看到的是：用户登录、校验身份、创建会话、返回用户信息。

架构视图看到的是：Frontend → API Server → Auth Service → Database / Redis。

时序视图看到的是：User → Frontend → API → AuthService → DB → Redis → API → Frontend。

数据视图看到的是：users 表用于身份校验，Redis 用于写入会话 token。

状态视图看到的是：anonymous → authenticating → authenticated，失败时进入 failed。

故障定位视图看到的是：登录失败可能来自前端参数、API 401、AuthService 校验、users 表数据、Redis 写入或 token 生成。

这些图看起来不同，但背后引用的是同一批节点和关系。这就是统一的核心：同源数据，多视图表达。

六、主干应该从功能出发，一路下钻到代码

如果没有主干，工程图谱很容易散掉。一个更自然的主干是从用户可感知的功能出发，一路下钻到实现细节：

业务能力 / 功能
    ↓
用户入口 / API / 命令 / 定时任务
    ↓
业务流程 / 调用链
    ↓
模块 / 服务 / 组件
    ↓
数据实体 / 状态 / 事件
    ↓
代码文件 / 函数 / 测试 / 日志

这种结构比从代码目录出发更适合人理解。因为用户、维护者和产品人员关心的不是仓库里有多少文件，而是某个功能在哪里、怎么实现、坏了怎么查、要改时会影响什么。

从功能到代码的路径，天然连接了业务语言和工程事实。它让非核心开发者可以先理解系统能力，让开发者可以快速定位实现，让维护者可以沿着路径查问题，让架构负责人可以观察模块边界和耦合风险。

但这并不意味着只能从功能进入。一个成熟系统应该至少支持三个入口：

• 从功能进入：我要理解某个能力如何实现。
• 从问题进入：用户报错、日志异常、接口失败，要定位可能根因。
• 从需求进入：我要新增或修改功能，要判断影响范围和实现路径。

这三个入口最终都应该落到同一张工程图谱，而不是三套互相割裂的文档。

七、四层地图：功能、流程、结构、演进

一个可用的软件工程地图系统，可以先组织成四层。

第一层是功能地图，回答“这个系统提供什么能力”。它面向产品、用户和新加入的开发者，例如用户与权限、项目管理、任务管理、通知、报表、系统设置等。

第二层是流程地图，回答“每个功能是怎么完成的”。它描述从用户动作到前端、API、权限校验、业务服务、数据写入、事件触发和结果返回的完整路径。

第三层是结构地图，回答“哪些模块支撑这些功能”。它把功能关联到页面、API、Service、Repository、数据表、事件、测试和代码文件。

第四层是演进地图，回答“改动会影响哪里”。它用于需求评估、重构评估和故障修复，展示新增字段、修改接口、删除模块、替换依赖时的影响范围和风险点。

这四层刚好对应软件维护的几个核心动作：先知道系统有什么，再知道流程怎么跑，再知道代码在哪里，最后知道如何安全改变。

八、视图需要有“契约”，不能随手生成

多视图系统如果没有约束，很容易变成“AI 想怎么画就怎么画”。每一种视图都应该有自己的视图契约，明确它回答什么问题、允许出现哪些节点、边代表什么含义、粒度应该到哪里为止。

例如，功能视图的契约可以是：

目标：回答系统提供哪些用户可感知能力
节点：Capability / Feature / Actor / Entry Point
边：contains / exposes / used_by
禁止：直接展示函数级调用，避免技术细节污染功能理解

流程视图的契约可以是：

目标：回答一次业务动作如何完成
节点：Actor / UI / API / Service / Entity / Event / External Dependency
边：calls / reads / writes / emits / triggers
要求：必须标记同步、异步、失败路径和事务边界

演进视图的契约可以是：

目标：回答一次变更会影响哪里
节点：Requirement / Feature / API / Service / Table / Test / Config / Deployment Unit
边：affects / depends_on / covered_by / requires_migration
要求：必须区分高置信影响、推测影响和待确认影响

视图契约的意义是让图变成工程工具，而不是视觉装饰。它限制信息粒度，避免每张图都塞满所有东西；也让不同图之间可以互相跳转，因为它们使用同一批对象类型和关系语义。

九、图之间应该通过导航关系连接

多视图系统最怕让用户迷路。因此，图与图之间必须能跳转，而不是只作为静态图片存在。

用户在功能地图里点击“创建任务”，应该能进入创建任务流程图；在流程图里点击 POST /api/tasks，应该能进入 API 调用链；点击 TaskService.create，应该能看到代码文件、函数定义、相关测试和最近修改；点击 tasks 表，应该能看到字段结构、读写点、迁移历史和相关报表。

一个理想路径类似：

功能地图 → 流程地图 → 模块地图 → 代码位置 → 测试 / 日志 / 风险

诊断路径则应该类似：

用户问题 → 功能入口 → 调用链 → 日志/Trace → 数据读写点 → 可疑代码

演进路径应该类似：

需求描述 → 相关功能 → 影响对象 → 修改点 → 测试点 → 发布风险

这就是工程地图区别于普通文档的地方：它不是让人被动阅读，而是允许人带着问题导航。

十、要服务三个闭环，而不是追求“画得全”

软件项目的关系太复杂，如果追求完整展示，很快就会不可用。工程地图应该优先服务闭环，而不是追求穷尽。

第一个是理解闭环：

功能 → 流程 → 模块 → 代码

第二个是诊断闭环：

问题 → 功能 → 调用链 → 日志 / 数据 → 可疑代码

第三个是演进闭环：

需求 → 影响范围 → 修改点 → 测试点 → 风险点

只要这三个闭环成立，这套系统就已经有实用价值。反过来，如果图画得很多，但不能帮助用户完成这三个闭环，那么它仍然只是漂亮文档。

十一、如何从代码中生成这张地图

工程地图不应该完全靠人工维护，否则必然过期。比较合理的生成方式是“自动抽取为主，人工和 AI 补全为辅”。

第一类信息可以从代码静态抽取：

• 文件、模块、类、函数、方法
• import / require / package 依赖
• API 路由、handler、controller
• 数据模型、schema、migration
• 测试文件和测试目标
• 配置项、环境变量、外部 SDK

第二类信息可以从运行时抽取：

• 请求 trace
• 日志上下文
• 任务执行链路
• API 实际调用频率
• 错误堆栈
• 慢查询和性能热点

第三类信息需要 AI 或人工补全：

• 功能归类
• 业务意图
• 模块职责
• 架构决策解释
• 异常路径总结
• 变更影响推断

因此，系统内部应该区分三种关系来源：

事实关系：代码、测试、schema、trace 可直接证明
推断关系：AI 根据命名、上下文和调用链推断
人工关系：开发者或维护者显式标注

这三种关系不能混在一起。事实关系可以直接作为导航基础；推断关系需要显示置信度；人工关系需要记录维护者和更新时间。这样图谱才能既自动化，又保持可信。

十二、如何避免它变成过期文档

静态文档最大的问题是过期。工程地图要有生命力，必须和代码变化绑定。

一种可行机制是：

1. 每次代码变更后，重新扫描受影响文件。
2. 找出新增、删除、修改的工程对象。
3. 更新相关边，例如调用关系、路由关系、读写关系、测试覆盖关系。
4. 标记受影响的视图为需要刷新。
5. 对 AI 推断和人工标注过的关系做“证据复核”：证据代码还在不在，行号是否变了，关系是否仍成立。
6. 在 PR 或提交摘要中提示：本次改动影响了哪些功能、流程、数据和测试。

这意味着工程地图不只是文档页面，还应该参与开发流程。它可以在 PR 中回答：

这次改动影响了哪些功能？
哪些 API 路径可能受到波及？
哪些数据表读写发生变化？
哪些测试覆盖了这些修改？
哪些视图因为代码变化需要重新生成？

如果做到这一步，工程地图就从“理解工具”进一步变成“变更控制工具”。

十三、MVP 不应该从大而全开始

第一版不应该追求覆盖所有图。更合理的 MVP 是围绕一个高频闭环先打穿。

最值得优先做的是“功能到代码”的理解闭环，因为它同时服务新人上手、AI 读仓库、维护定位和后续影响分析。

一个可控 MVP 可以包含：

1. 扫描仓库，抽取文件、模块、函数、路由、数据模型和测试。
2. 让 AI 基于 README、路由、页面、测试和命名生成初版功能地图。
3. 把每个功能关联到入口、API、服务、数据实体和代码证据。
4. 为每个功能生成一张流程图和一张结构图。
5. 支持点击节点跳回代码位置。
6. 支持输入一个需求或问题，返回相关功能、模块和可能影响点。

第一版可以暂时不做完整部署图、复杂状态机和全量 runtime trace。它们很有价值，但不是起点。起点应该是把“我想理解这个功能”这件事做到低成本、可信、可下钻。

十四、从静态网页到可操作的工程工作台

如果这些图只是静态网页，价值会停留在“看懂”。但真正有用的产品不应该只让用户看图，而应该让用户在图上完成工程动作：筛选、下钻、提问、标注、修正、验证、生成计划、模拟影响，最后把结果带回代码、测试、PR 或运行时排障流程。

因此，这个产品的形态不应该是“文档站 + 一些图”，而应该是一个 交互式工程工作台。图只是工作台的主界面之一，用户面对的不是图片，而是一张可以操作的系统地图。

静态网页的默认动作是阅读；交互式工作台的默认动作是操作。这个转变很关键。一个节点不再只是图形元素，而是一个可以被打开、质疑、修正、收藏、加入变更计划、关联测试、生成说明的工程对象。

十五、用户不是看图，而是在图上完成任务

交互设计应该从用户任务出发，而不是从图的种类出发。最重要的三类任务仍然是理解、诊断和演进。

理解任务的典型路径是：用户搜索“创建任务”，系统定位到功能节点，展示它的入口、流程、模块、数据和测试；用户可以逐层展开，也可以只看高层摘要。这个过程里，图负责空间化展示关系，右侧面板负责展示证据和解释，AI 负责把当前子图翻译成自然语言。

诊断任务的典型路径是：用户输入“创建任务失败”或粘贴一段错误日志，系统把问题映射到相关功能、API、服务、数据表和最近变更；用户可以沿着调用链检查日志、trace、错误堆栈和读写点。诊断视图不应该默认展示全量架构，而应该展示一条可排查路径。

演进任务的典型路径是：用户输入“给任务增加优先级字段”，系统先找到相关功能和数据模型，再列出可能影响的 API、Service、表结构、前端页面、筛选排序逻辑、通知模板和测试。用户可以把这些节点加入“变更篮”，形成一份修改计划。

因此，产品里每个视图都应该有明确动作，而不是只支持浏览：

• 点击节点：查看职责、证据、相关代码、测试和运行时数据。
• 双击节点：聚焦到该对象，隐藏无关噪音。
• 展开邻居：显示上游、下游、读写对象、调用对象或覆盖测试。
• 切换层级：从功能层下钻到 API、模块、函数，或从函数上卷到功能。
• 框选子图：对一组节点提问、生成说明、导出文档或加入变更篮。
• 标注关系：人工确认、否定或补充一条 AI 推断关系。
• 模拟改动：选择一个节点或需求，查看可能影响范围。
• 生成计划：把当前子图转成开发任务、测试清单或 PR 说明。

图的价值不在于“展示了多少信息”，而在于用户能不能在图上把一个工程问题推进到下一步。

十六、交互式产品的信息架构

一个通用产品可以采用五区布局。

顶部是意图入口。它不应该只是搜索框，而应该让用户选择当前任务：理解功能、诊断问题、评估变更、生成文档、查看架构、审查 PR。不同意图会改变默认视图、过滤器、右侧操作和 AI 提示词。

左侧是视图和过滤器。用户可以在功能、流程、结构、数据、状态、部署、诊断、演进等视图之间切换；也可以按模块、置信度、风险、运行热度、最近变更、是否有测试覆盖进行过滤。

中间是图谱画布。它不是普通画布，而是支持层级展开、聚焦、折叠、路径高亮、邻居探索、子图选择、布局切换的操作空间。图谱画布应该避免一次性展示全量关系，默认只展示与当前问题有关的最小子图。

右侧是对象详情和操作面板。当用户选中节点或边，右侧显示它的定义、职责、证据、来源、置信度、代码位置、测试覆盖、日志/trace、最近变更和可执行动作。右侧面板决定这个产品是否真的可用，因为它把视觉节点变成可验证的工程事实。

底部是时间线和变更篮。时间线展示图谱如何随 commit、PR、版本、部署而变化；变更篮则允许用户把一组受影响对象收集起来，生成实施计划、测试计划、风险说明或 PR checklist。

这五区共同构成一个工作台：顶部表达意图，左侧选择视角，中间操作关系，右侧验证证据，底部管理变化。

十七、核心交互模式

交互式工程地图至少需要六种核心模式。

第一种是Lens 模式。同一张图谱可以套不同镜头：功能镜头、调用镜头、数据镜头、状态镜头、风险镜头、测试镜头。Lens 不改变底层数据，只改变展示规则。例如风险镜头会突出高耦合、无测试覆盖、频繁变更和低置信度关系；测试镜头会突出哪些功能缺少覆盖。

第二种是Drill-down / Roll-up 模式。用户可以从业务能力下钻到功能、入口、API、服务、函数和代码，也可以从一个函数反向上卷到它支撑的功能。这个能力让产品同时服务产品视角和代码视角。

第三种是Path Finding 模式。用户选择两个对象，系统回答它们之间有什么路径。例如“这个页面为什么会影响这个表？”“这个错误日志对应哪个功能？”“这个测试覆盖了哪些 API？”路径查找比全局图更有用，因为它把关系变成具体问题的答案。

第四种是What-if 模式。用户选择一个节点或输入一个需求，系统生成潜在影响范围。What-if 不应该伪装成确定事实，而应该区分高置信影响、推测影响和待确认影响。

第五种是Annotation 模式。开发者可以确认或否定一条关系，补充模块职责，写下架构决策，标记一个节点为危险区或废弃区。人工标注不是文档旁路，而是图谱的一等数据。

第六种是Plan 模式。用户框选一组节点，系统生成开发计划、测试计划、排障步骤、重构边界或文档摘要。Plan 模式是从“理解系统”走向“改变系统”的关键。

十八、节点和边的操作语义

一个节点至少应该支持这些操作：

Open：打开详情
Focus：只看与它相关的子图
Expand：展开上游/下游/调用/读写/测试/部署关系
Explain：让 AI 解释它的职责和上下文
Open Code：跳到代码位置
Show Evidence：查看证据、来源和置信度
Add Annotation：添加人工说明
Add to Change Basket：加入变更篮
Find Impact：查找变更影响
Find Path：查找它与另一个对象的路径

一条边也应该是可操作对象，而不是简单线条。边需要展示关系类型、方向、证据、来源和置信度。例如 TaskService.create writes tasks 这条边，应该能打开到具体代码行、ORM 调用、SQL trace 或测试断言。用户也应该能标记这条边为“已确认”“错误”“过期”“需要复核”。

这意味着产品的数据模型里，Edge 不能只是 source_id 和 target_id，还要包含：

type：calls / reads / writes / emits / depends_on / covered_by / affects
source：static_analysis / runtime_trace / ai_inference / human_annotation
confidence：0.0 - 1.0
evidence_refs：代码位置、trace、测试、文档或人工说明
valid_from / valid_to：在哪些版本中有效
review_state：unreviewed / confirmed / rejected / stale

只有当边也能被检查和修正时，图谱才会逐渐变得可信。

十九、AI 在交互产品里的位置

AI 不应该只是“生成一张图”。在交互式产品里，AI 更适合扮演四个角色。

第一，AI 是解释器。用户选中一个子图，AI 把它解释成自然语言：这个功能从哪里进入，经过哪些模块，读写哪些数据，可能有哪些风险。

第二，AI 是抽取器。它从 README、代码命名、测试、注释、PR 描述和运行日志中抽取功能、职责、异常路径和架构意图。但抽取结果必须带来源、置信度和可复核证据。

第三，AI 是推演器。当用户输入需求或故障描述时，AI 基于图谱推断相关节点和可能路径，但它必须明确区分事实和推测。

第四，AI 是计划生成器。当用户确认影响范围后，AI 可以生成开发计划、测试清单、迁移步骤、PR 描述和风险说明。

但 AI 不应该直接替代工程事实。产品应该明确限制：AI 可以建议关系，但事实关系必须来自代码、测试、schema、trace 或人工确认；AI 可以生成计划，但不能把计划伪装成已完成的修改；AI 可以解释风险，但必须说明依据。

二十、通用产品的数据模型

为了支持交互和操作，底层模型至少需要这些一等对象：

Project：一个代码仓库或多仓系统
Snapshot：某个 commit / branch / release 对应的图谱快照
Node：工程对象，如 Feature、API、Service、Table、Test
Edge：对象关系，如 calls、writes、covered_by、affects
Evidence：证据，如代码行、trace、日志、测试、文档段落
View：视图定义，如功能视图、诊断视图、演进视图
Lens：展示镜头，如风险、测试、性能、最近变更
Annotation：人工标注、确认、否定、解释
Scenario：用户的一次理解、诊断或演进任务
ChangeBasket：用户收集的一组影响对象
Plan：由子图生成的开发、测试、排障或重构计划

其中 Snapshot 很关键。没有快照，图谱就无法表达变化；没有变化，工程地图就无法参与 PR、发布和故障回溯。用户应该能比较两个快照：这个版本新增了哪些 API？哪些功能受影响？哪些测试覆盖变化？哪些手工标注变成了 stale？

Scenario 也很关键。它把用户的一次工作上下文保存下来：输入的问题、查看过的节点、确认过的关系、生成过的计划、最后采取的动作。这样产品不会只是一个浏览器，而会成为工程工作的记录系统。

二十一、权限、协作和安全边界

如果这个产品用于团队，交互能力必须有权限边界。

只读用户可以浏览图、搜索、下钻和查看证据。维护者可以确认关系、添加标注、调整功能归类。架构负责人可以编辑视图契约、确认架构决策、标记废弃模块和风险区域。CI 或机器人可以写入静态分析和运行时 trace，但不能覆盖人工确认。AI 可以创建候选关系和候选说明，但默认进入待复核状态。

更重要的是，图上的操作要区分“分析动作”和“代码动作”。点击“生成修改计划”可以直接做；点击“创建 PR”“修改代码”“执行迁移”则必须进入明确的确认和外部工具流程。工程地图应该降低理解和规划成本，但不应该绕过代码审查、测试和发布纪律。

二十二、MVP 应该先做成什么样

如果从交互产品角度重新定义 MVP，第一版可以更明确：做一个 功能中心的交互式代码地图。

第一版的核心页面可以只有一个工作台：

顶部：搜索/提问/选择意图
左侧：功能列表和视图切换
中间：当前功能的交互式子图
右侧：选中节点的证据、代码、测试和 AI 解释
底部：变更篮和当前路径

第一版必须支持这些动作：

1. 输入功能名或自然语言问题，定位到相关功能。
2. 展示该功能的入口、API、服务、数据实体和测试。
3. 点击节点查看证据和代码位置。
4. 展开上游/下游邻居，但默认限制半径，避免毛线球。
5. 对当前子图提问，让 AI 基于节点和证据回答。
6. 框选节点生成“这个功能如何实现”的说明。
7. 输入一个小需求，生成初版影响范围和测试清单。

第一版明确不做：全仓库大图、复杂权限系统、完整 APM、自动改代码、全量状态机建模、复杂团队协作。它先把交互式理解闭环做扎实。

一个可验收的 MVP 标准是：给一个中等规模仓库，用户能在 5 分钟内回答三个问题：

某个功能的入口在哪里？
这个功能主要经过哪些模块和数据对象？
如果我要改它，至少应该看哪些代码和测试？

如果这三个问题能通过交互地图可靠回答，产品就已经不是静态文档了。

二十三、它更像一个软件理解系统，而不是文档系统

从产品形态上看，这个方向位于 IDE、架构文档、代码知识图谱、Observability、软件设计工具和 AI 代码助手之间。

它既不是传统 README，也不是静态 UML，也不是单纯的代码搜索。它应该能把代码事实、运行事实和设计意图组织起来，让用户围绕功能、问题和变更进行查询、操作和推演。

更准确的定义是：

基于统一工程知识模型的交互式多视图软件理解系统。它将代码库中的功能、模块、接口、数据、状态、事件、部署、测试和故障信息抽象为统一的工程知识图谱，再根据不同使用场景生成可操作的功能图、架构图、流程图、数据流图、状态机图、依赖图和影响分析图。不同图并不是彼此孤立的文档，而是同一套工程对象的不同交互视角。用户可以从业务功能出发，逐层下钻到流程、模块、数据和代码；也可以从故障、需求或变更点出发，反向追踪相关影响范围，并把子图转化为排障步骤、修改计划、测试清单或架构说明。

二十四、当前最精炼的产品命题

这件事可以先压缩成三句话：

用统一的工程知识图谱承载系统事实，用多视图图形化承载不同问题场景。

底层是一张代码知识图谱，表层是一组面向理解、诊断和演进的交互式工程地图。

不是把所有图合成一张图，而是让所有图来自同一个模型、指向同一个代码事实、服务同一个工程闭环，并允许用户在图上完成操作。

如果继续产品化，它的核心卖点可以进一步表述为：

让代码库从“只能被阅读”变成“可以被导航、查询、解释、诊断、标注、验证和推演”。

后续迭代应该继续围绕几个问题展开：

1. 统一工程对象模型应该如何定义？
2. 哪些关系可以从代码自动抽取，哪些需要人工或 AI 补充？
3. 第一版应该优先支持哪些视图，避免一开始做成大而全？
4. 如何从功能、问题、需求三个入口进入同一张工程图谱？
5. 如何让图谱保持随代码变化而更新，而不是变成过期文档？
6. AI 在其中应该负责解释、抽取、补全、问答，还是负责生成变更方案？
7. 视图契约如何设计，才能避免每张图都变成信息垃圾场？
8. 图上的哪些操作应该只是分析，哪些操作可以进入开发、测试和 PR 流程？
9. 如何设计 Snapshot、Scenario 和 ChangeBasket，让工程地图成为工作记录，而不是一次性可视化？

这篇文档当前的基线结论是：目标不是“代码画图工具”，而是“面向理解、诊断和演进的交互式软件工程地图工作台”。