架构勘探 lvxinrong/dsh-archscope

ArchScope

面向复杂、多仓软件系统的证据驱动架构勘探引擎——为 DeepSeek Harness 而生。

先看清系统，再修改代码。

ArchScope 希望帮助 AI Agent 真正接手一个陌生软件系统，而不只是浏览目录、统计文件或生成一篇看似完整的架构总结。

它把源码发现、证据采集、系统建模、项目画像、层级门禁、并行编排、结果校验和架构门户组织成一套可恢复、可验证、可扩展的扫描协议，并以 DeepSeek Harness 插件的形式提供这些能力。

项目状态：v0.3.3 在系统事实底座、统一项目批处理、确定性专长路由和短任务信封协议闭环之上，增加了父流程拥有的 Spring 确定性事实与项目证据分页输入；npm 包尚未发布。 ArchScope 可以发现 Git 工程，为每个工程建立或复用独立索引，完成系统级并行取证与主 Agent 综合；系统门禁通过后，单项目和多项目都由同一个批处理执行器完成隔离深取证、项目专属 Agent 无损综合、固定模板校验、冲突记账和版本化发布。运行态证据与失败恢复仍在开发中。

核心模型：系统级定世界观，项目级定工程画像，模块级定内部边界，代码级定具体链路。

模块分析横向梳理能力与职责，代码分析纵向追踪真实执行路径。

为什么需要 ArchScope

当一个 Agent 第一次进入大型代码库时，最容易得到的是“局部正确、整体失真”的答案：

- 看见一个依赖，就推断它已经在生产环境启用；
- 看见几个目录，就把它们当成系统的真实业务边界；
- 扫描单个仓库，却忽略它在多工程系统中的角色；
- 生成大量自然语言结论，却没有可追溯证据；
- 并行派发多个任务，却缺少统一事实底座和冲突仲裁；
- 一次会话中断后，无法判断已经完成了什么、哪些结果仍然可信。

ArchScope 的出发点是：

架构理解不是一次性的代码摘要，而是一条从证据到结论、从局部到整体、可以校验和恢复的工程流程。

ArchScope 有什么不同

证据优先，而不是结论优先

每个重要结论都应指向可复核的证据。无法证明的内容必须标记为待确认；源码中存在的能力，不等于生产环境实际启用。

先建立系统世界观，再分析单个项目

ArchScope 不会让多个 Agent 在没有共同语境的情况下各自解释系统。系统级事实底座先统一生产边界、工程身份、基础设施、入口和术语，项目级分析再继承这些事实。

模型负责推理，程序负责纪律

适合判断和归纳的工作交给模型；状态机、任务计划、契约校验、身份解析、批次恢复、精确关系统计、可移植路径检查和凭据秘密检查交给确定性程序。

从第一天支持多仓系统

项目身份使用工作区相对路径，而不是目录 basename。同名仓库、嵌套仓库、聚合目录和复合工程不会被静默合并。

原生融入插件运行时

ArchScope 不是把一份长提示词套进 npm 包。它计划以 Cordis 服务、模型工具、能力 Provider 和 Harness bundle 的方式接入 DeepSeek Harness，让扫描能力可以被组合、替换、热更新和复用。

分析模型

ArchScope 使用分层模型控制分析顺序和结论边界：

| 层级 | 回答的问题 | 主要产物 |
| 系统级 | 这是一个怎样的系统？边界、入口、工程和基础设施是什么？ | 系统级事实底座 |
| 项目级 | 这个工程在系统中扮演什么角色？如何构建、运行和依赖外部能力？ | 工程画像 |
| 项目内部地图 | 源码中有哪些业务能力候选、技术组件和契约组件？ | 可导航的项目地图 |
| 模块专题 | 某项职责相关代码的边界、入口、数据和依赖如何组织？ | 模块专题报告 |
| 代码链路 | 某个接口、任务、消息、异常或数据流具体如何执行？ | 可追踪的执行链路 |

项目内部地图是可选导航，不宣称给出唯一正确的模块划分。模块专题和代码链路都依赖项目级画像，但二者互不依赖。

项目级专长路由

项目级扫描不是一个通用 Agent 临场猜工程类型。父协调器先根据工程内的确定性信号冻结专长与模板，再分别派发专属证据 Agent 和专属写作 Agent：Spring 后端 Java、Vue Web、微信小程序、原生 Android、原生 iOS 与通用工程彼此隔离。只有证明存在 Spring Framework / Spring Boot / Spring Cloud 可执行服务边界的 Java 工程才能进入 Spring 后端 Agent；只有 pom.xml 或 Gradle 文件的 SDK、父工程和公共库使用通用 Agent。React Native/Flutter 的生成目录不作为原生 Android/iOS 证据；同一分析单元命中多个独立应用类型时会停止派发，要求先拆分或显式裁决。

Spring 后端项目级分析固定覆盖服务身份与启动边界、Spring 版本/BOM/自动配置、HTTP/RPC/MQ/任务入口、分层与模块、出站调用与韧性、数据访问与事务一致性、配置中心与覆盖缺口、安全边界、可观测性、部署运行、测试、统计口径、项目级链路候选、风险和模块候选。源码与配置结论不会被写成生产运行事实。

父协调器还会为 Spring 后端生成独立的 DETERMINISTIC_FACTS 数据集和 deterministic-facts.json：Maven 模块、本地配置文件、Controller/Mapper 文件及受支持的 Spring 注解数量都由受限文件扫描直接产生。Agent 只能解释，不能覆盖这些指标；统计章节由机器数据生成，正文或图表里的冲突数量以及未经允许的“0 个/未发现/全部外部化”结论会阻断发布。

证据 Agent 和写作 Agent 的首次输入只包含短任务信封：runId、工程身份、冻结专长、上下文工具名和版本化资源 ID。系统事实、安全元数据、通用规则、专长检查项及 Markdown 模板不会内联进首条提示词，而是通过只读工具按需获取。证据阶段固定先无损分页读取父流程已脱敏的 SAFE_METADATA 与 DETERMINISTIC_FACTS，再读取项目对应的系统证据和系统事实底座；超大记录按字节游标拼接，避免长上下文尾部信息被忽略。服务端按 run 状态和冻结专长计算白名单：证据阶段只能读取通用证据规则、冲突规则、证据契约和当前专长检查项；写作阶段只能读取写作协议、分析/校验策略、文档契约和当前模板。所有读取会写入账本，必需数据集或资源未读全时拒绝推进或提交。

工作方式

flowchart LR
A["工作区与多仓源码"] --> B["工程发现与能力索引"]
B --> C["系统级事实底座"]
C --> D["项目级工程画像"]
D --> E["项目内部地图"]
D --> F["模块专题"]
D --> G["代码链路"]
C -. "事实继承" .-> D
H["证据保真与凭据规则"] -.-> C
H -.-> D
I["契约、门禁与校验"] -.-> C
I -.-> D
I -.-> E
I -.-> F
I -.-> G
C --> J["文档、机器状态与架构门户"]
D --> J
E --> J
F --> J
G --> J

一次完整扫描不是单个大 Prompt，而是由多个可检查阶段组成：

1. 递归发现真实 Git 工程并建立稳定身份；
2. 选择并记录代码发现能力，例如代码图谱、LSP 或文件搜索；
3. 采集系统级证据，由单一写者统一术语并仲裁冲突；
4. 通过系统级门禁后，再按项目隔离上下文进行分析；
5. 使用不可变任务快照和运行状态组织并行任务；
6. 对文档结构、证据引用、状态字段和敏感值执行确定性校验；
7. 在需要时继续进入项目地图、模块专题或代码链路；
8. 汇总为人类可阅读的报告和可导航的系统架构门户。

当前 MVP 使用体验

ArchScope 计划让用户通过 Harness 工具用自然语言表达目标。当前对用户提供 archscope_scan_system、archscope_scan_projects、兼容入口 archscope_scan_project 与 archscope_status；扫描内部还注册综合上下文、无损分页、单产物暂存与最终发布工具，更深层的分析能力会继续复用同一个服务边界。

为这个工作区建立系统级事实底座。

分析 order-service 在整个系统中的角色。

并行扫描所有满足门禁的项目，失败任务保留现场并允许恢复。

追踪下单接口从 Controller 到数据库与消息发布的完整源码链路。

需要确定性控制或脚本化调用时，同一组意图使用统一、严格的命令命名空间：

/archscope system [--refresh]
/archscope project <project-key> [--refresh]
/archscope projects --all [--refresh]
/archscope projects <project-key...> [--refresh]
/archscope help

命令同时接受 系统级扫描、项目级扫描 与 帮助 中文子命令别名。Slash command 使用严格解析，不猜测错误输入；参数不合法时只返回用法说明。system 会依次完成工程发现、独立索引和逐工程证据采集，随后自动把运行交给当前 DSH 主 Agent；主 Agent 加载完整系统协议和结构化 evidence，综合事实底座与三张图，再交由插件执行确定性校验。整个过程会在主对话中汇报阶段与四分位进度。首次扫描或 --refresh 可能耗时较长；普通扫描会按工程绝对根路径复用已有索引。已完成或正在等待主 Agent 综合且协议版本一致的运行可以复用，BLOCKED 运行会在下次执行时重新尝试。

DeepSeek Harness 当前不会在完全空白的新会话中分发 Slash Command。请先选择已有会话，或发送一条普通消息创建会话后再运行 /archscope。命令候选项本身也会显示这项限制，避免第一次交互静默失败。

/archscope 与 /archscope help 会把使用指南作为正常的助手回复发布到对话中，命令结果本身不再承载长文本，避免帮助内容看起来像工具卡片或 Think 记录。

源码视角的索引和证据全部完成后，系统门禁可以进入 READY；这仍不等于生产拓扑已得到确认。缺失 MCP 工具、索引失败、worker 失败或越界读取都会让门禁保持 BLOCKED。system、project、projects 与 help 是当前公开的 Slash Command。项目扫描只接受绑定系统工程注册表中的精确 projectKey，并要求系统状态为 COMPLETED / PASSED / READY。单项目只是批次大小为 1；多项目会固定绑定同一个系统事实版本，以有界并发为每个工程运行隔离取证 Agent 与项目专属写作 Agent，当前主 Agent 只接收批次结果。项目产物仍拆成一份画像与三张图逐项暂存，四项齐全后才发布。无效证据路径最多定向修复一次；单工程失败不会抹掉其他工程结果。

项目结论与系统事实不一致时不会静默覆盖上层。每条差异会进入项目与批次冲突账本：普通细化无需复核；源码矛盾或跨工程矛盾标记为 OPEN，可以在产物校验通过时继续发布；上游版本陈旧或工程身份不一致属于阻断型冲突，只把对应项目的下层门禁置为 BLOCKED。批次执行期间禁止修改绑定的系统事实，后续由独立系统单写者复核并在必要时生成新的系统版本。

后续模型工具会围绕以下能力继续扩展：

scan system
scan project
scan all projects
build project map
scan module
trace code
show status
resume run
validate artifacts

我们希望用户面对的是一组清晰的分析意图，而不是一长串平台特定命令。

当前系统级扫描产物

ArchScope 默认只在独立输出目录中写入分析产物，不修改业务代码：

archscope_docs/
├── system/
│ ├── 00-system-fact-base.md
│ ├── project-registry.json
│ ├── index-manifest.json
│ ├── evidence/
│ │ ├── index.json
│ │ └── <project-key>.json
│ ├── relations.json
│ ├── protocol-lock.json
│ ├── synthesis.json
│ ├── validation.json
│ ├── history.json
│ └── diagrams/
│ ├── 01-system-context.mmd
│ ├── 02-internal-relations.mmd
│ └── 03-entry-overview.mmd
├── runs/
│ ├── latest.json
│ └── <run-id>/
│ ├── state.json
│ ├── system/ # 不可变终态快照 │ │ ├── 00-system-fact-base.md │ │ ├── evidence/ │ │ └── diagrams/ │ └── synthesis/ │ └── attempt-<n>/ │ ├── attempt.json │ ├── 00-system-fact-base.md │ └── diagrams/ ├── project-batches/ │ ├── latest.json │ └── <batch-id>/ │ ├── state.json # 项目结果信封与失败隔离状态 │ └── conflicts.json # 固定系统版本下的冲突聚合账本 └── projects/<project-key>/ ├── 00-project-profile.md ├── deterministic-facts.json # Spring 父流程确定性事实 ├── conflicts.json └── history.json

system/ 始终代表最近一次校验通过并正式发布的事实底座。新扫描会先把工程注册表、索引和 evidence 暂存在自己的 runs/<run-id>/system/ 中，因此扫描进行中或最终校验失败都不会覆盖上一版可用文档。每次进入终态的系统综合都会获得 S0001 这样的递增事实版本；终态快照和每次综合尝试默认全部保留。system/history.json 负责关联事实版本、run id、校验与门禁状态、不可变产物路径，以及当前发布版本。

每个工程的原始结构化证据先写入独立文件，系统事实底座只由当前 DSH 主 Agent 综合，避免并行 worker 互相污染或竞争写文档。主 Agent 首先获得约束在 DSH 内联阈值以内的协议与读取清单，再通过 archscope_get_system_synthesis_page 按 UTF-8 字节预算顺序读取工程注册表、索引、完整关系目录和全部单工程 evidence。分页只改变传输批次，不压缩、不摘要、不截断；超大单条记录会在 UTF-8 字符边界处分片并按字节偏移无损重组。每页、每条记录和每个数据集都有 SHA-256 摘要，服务端将游标、覆盖记录和页摘要持久化到当前 run 的 synthesis/read-ledger.json；四个数据集未全部覆盖时拒绝提交。主 Agent 仍负责跨工程理解、术语统一、关系判断、冲突仲裁和最终表达，正则分类与名称匹配只作为候选输入。

插件会记录主写者会话、模型和输入输出摘要到 system/synthesis.json，并把每次提交的草稿及校验结果保存在当前 run 的 synthesis/attempt-<n>/ 目录。确定性校验会覆盖文档结构、证据边界、正文与机器关系统计是否一致、本机绝对路径、可直接定位的原子工程相对证据文件、真实凭据泄漏、图表边语义，以及真实“阻断项目级”问题与下层门禁是否一致。工程清单与历史旁支章节还会阻止 Controller、方法、源码文件、配置审计和缺陷细节越过系统级边界。具体路由、代码符号、配置与实现细节仍保留在逐工程 evidence JSON 中。源码证据齐备且没有真实项目级阻断项时，文档可以标记为“完整（源码视角）”并打开项目级门禁；运行态事实仍会明确标记为待确认，综合校验通过也不等于生产架构已经得到证明。

代码定义、路由和调用关系优先由 codebase-memory 提供。对于图谱容易遗漏的 manifest、README、CI、容器和部署配置，ArchScope 会在父进程中执行工程根目录约束、符号链接拒绝、文件与总量限制以及真实凭据移除，再把安全元数据基线交给证据 worker。本地事实产物会保留真实服务名、域名、IP、路由、表名、Topic、Queue 等架构标识。worker 不会获得任意文件读取、shell 或写入能力。

系统级 Protocol Pack

ArchScope 将系统级分析知识作为版本化的 protocol/ 目录随插件发布。协议包包含证据、工程身份、索引状态、22 章节系统文档与层级门禁的机器契约；包含分析边界、本地事实保真与凭据处理、输出路径和校验策略；也包含会被真实注入当前 DSH 主 Agent 的完整系统主写者指令，以及只读 evidence worker 的聚焦提示。

插件会在运行时加载并校验这份目录。每次扫描都会生成 system/protocol-lock.json，记录协议包版本、manifest 以及每个资源的 SHA-256 摘要。协议包发生变化后，ArchScope 会创建新运行，不会静默复用旧规则下的结果。适合程序执行的约束已经迁入 TypeScript 并由测试守护；Markdown 是可审阅的协议正文，而不是无人执行的附件。

配置

| 配置项 | 默认值 | 作用 |
| workspaceRoot | 当前 DSH 会话工作区 | 可选扫描根覆盖；相对路径以会话工作区为基准解析 |
| outputDirectory | archscope_docs | 工作区内部的产物目录 |
| discoveryMaxDepth | 3 | 递归发现 Git 根的最大深度 |
| codebaseMemoryServerName | codebase_memory_mcp | codebase-memory MCP 工具的 DSH namespace |
| indexMode | moderate | 新建或刷新索引时使用的 fast / moderate / full 模式 |
| evidenceProvider | spawn | 用于逐工程只读证据任务的 DSH subagent provider |
| systemConcurrency | 4 | 索引和证据任务的最大并发数 |
| projectConcurrency | 4 | 项目批次中完整工程执行链路的最大并发数 |
| evidenceContextMode | auto | 兼容保留，当前已忽略；系统综合固定使用无损分页，不压缩、不截断 |
| fullEvidenceMaxBytes | 524288 | 兼容保留，当前已忽略；分页字节预算由协议固定管理 |
| registerCommand | true | 注册可选的 /archscope 命令 |
| registerSystemScanTool | true | 注册 archscope_scan_system 与系统综合工具 |
| registerProjectScanTool | true | 注册 archscope_scan_projects、兼容单项目入口与项目综合工具 |
| registerStatusTool | true | 注册 archscope_status |
规范命名记录在 docs/brand.md。

ArchScope bundle 会同时挂载 DeepSeek Harness 官方 @deepseek-ai/dsh-mcp-client，并通过 stdio 启动 codebase-memory-mcp。因此运行前需要确保该可执行文件在启动 DSH 的 PATH 中：

command -v codebase-memory-mcp

安装插件后，可用下面的命令确认 MCP 与 ArchScope 两个配置层都已出现：

dsh --profile web --dump-config | rg -n -C 6 "archscope-codebase-memory|codebase_memory_mcp|dsh-archscope"

本地开发可执行 pnpm install，随后运行 pnpm check。ArchScope 目前尚未发布到 npm，公开安装命令会随首个版本一并提供。

插件架构方向

ArchScope 计划采用以下内部边界：

ArchScope Bundle
├── ArchScope Service
│ ├── 扫描状态机 │ ├── 任务与恢复 │ ├── 产物管理 │ └── 契约校验 ├── Model-facing Tools ├── Capability Providers │ ├── Code Intelligence │ ├── Workspace Discovery │ ├── Subagent Orchestration │ └── Runtime Evidence ├── Analysis Protocol │ ├── Prompts │ ├── Evidence Rules │ └── Layer Gates └── Report & Portal Generator

代码图谱会是优先的代码发现方式，但不会成为唯一实现。ArchScope 将尽量通过能力接口支持 codebase-memory、LSP、文件搜索以及未来的其他 Provider。

发现与分发

ArchScope 将遵循 DeepSeek Harness 的官方插件发现约定。公开发布时，GitHub 仓库会添加精确的 dsh-plugin Topic，使其能够进入 Harness 插件生态的发现入口。

可发现只是第一步。每个正式版本还必须同时满足：

- 以包含 dsh.bundle manifest 的可安装 bundle 交付；
- 提供预构建 npm 包，避免普通用户在安装时构建源码；
- 支持通过 dsh plugin --profile <name> add <package> 安装和移除；
- 能在 dsh --profile <name> --dump-config 中确认 ArchScope 配置层；
- 在 README 中提供可复制的安装命令、兼容版本和最小验证步骤；
- 使用语义化版本、GitHub Release 和明确的迁移说明管理兼容性变化。

被 Topic 检索到不代表获得 DeepSeek 官方认证。ArchScope 会把“可以发现、可以安装、可以验证”作为同一套发布门禁，而不是只添加一个标签。

设计原则

- 证据可追溯：重要结论必须能够回到源码、配置、运行态材料、运维文档或人工确认。
- 事实有边界：严格区分“源码可见”“配置声明”“运行态确认”和“生产启用”。
- 不确定性显式化：缺失、冲突和低可信信息是正式结果的一部分。
- 上层事实可继承：下层分析发现冲突时回传复核，不静默改写系统世界观。
- 确定性门禁：能由程序判断的规则，不依赖模型自觉遵守。
- 上下文隔离：单项目和单模块任务只接收完成任务所需的最小上下文。
- 可恢复执行：长时间、多项目扫描必须能够查看状态、记录失败并从中断处继续。
- 本地事实保真：默认产物精确保留架构标识；未来的分享脱敏只能生成派生副本，不改写事实底座。
- 安全默认值：默认不修改业务代码，不输出密钥、令牌、密码、私钥、API Key 或嵌入式凭据。
- 模型与工具可替换：核心协议不绑定某个特定模型、索引引擎或代码搜索工具。

ArchScope 不是什么

- 不是代码行数、目录和依赖数量的统计器；
- 不是把所有仓库一次性塞进上下文的超长 Prompt；
- 不是仅凭源码推断生产拓扑的架构幻想生成器；
- 不是替代架构师、开发者和运维确认的自动真相机器；
- 不是默认修改或“顺便重构”被扫描业务代码的编码 Agent。

ArchScope 的目标是提供一份更可信的认知起点，以及一条可以持续深化和复核的分析路径。

路线图

阶段一：最小可信闭环

- [x] 建立独立的 TypeScript 插件工程与 Harness bundle
- [x] 定义 ArchScope Service、配置 schema 和基础工具
- [x] 完成多仓工程发现与稳定项目身份
- [x] 打包系统级机器契约、策略、提示与协议锁
- [x] 跑通独立索引、只读证据采集、系统事实底座生成与确定性校验
- [x] 提供无需真实模型 API 的插件和工具流水线测试

阶段二：项目级与可恢复编排

- [x] 单项目隔离扫描
- [x] 工程类型识别与模板选择
- [ ] 不可变任务快照、批次状态和失败恢复
- [x] Subagent Provider 接入（系统级只读证据 worker）
- [x] 项目级文档契约、无损综合、事实版本与质量门禁

阶段三：深入分析与系统地图

- [ ] 项目内部地图
- [ ] 模块专题分析
- [ ] 代码执行链路追踪
- [ ] 架构门户
- [ ] 运行态证据 Provider

阶段四：开放生态

- [ ] 稳定 Provider 接口
- [ ] 第三方工程类型与报告 Profile
- [ ] 自定义证据源和组织级规则包
- [ ] Headless、Web 与自动化工作流集成
- [ ] 分享安全/公开发布导出命令：生成脱敏副本但不修改本地事实产物
- [ ] 发布预构建 npm bundle，并验证标准安装和移除流程
- [ ] 添加 dsh-plugin GitHub Topic，并验证生态发现入口可检索 ArchScope

路线图会随着 DeepSeek Harness 的 Developer Preview API 演进而调整。

参与项目

ArchScope 目前最需要的不是大量功能代码，而是对问题边界和协议设计的共同打磨。欢迎围绕以下主题参与讨论：

- 大型多仓系统接手时，最难确认的事实是什么？
- 哪些架构结论必须由运行态证据支持？
- Agent 并行分析最常见的上下文污染和冲突是什么？
- 什么样的报告契约既适合人阅读，也适合机器校验？
- 哪些代码智能 Provider 值得优先支持？
- 如何衡量一次架构扫描“可信”，而不只是“内容很多”？

在第一个稳定版本发布前，接口、命名和目录结构都可以讨论；一旦形成公开契约，我们会优先保持迁移路径和兼容说明。

开源许可

ArchScope 基于 MIT License 开源。

致谢

- DeepSeek Harness：提供“Everything is a Plugin”的 Agent Harness 与 Cordis 插件运行时。

ArchScope 不试图替你画一张漂亮但未经证明的架构图。它更关心：图上的每一条重要结论，是否知道自己从哪里来。