# ArchScope

[English](./README.md) | **简体中文**

> 面向复杂、多仓软件系统的证据驱动架构勘探引擎——为 [DeepSeek Harness](https://github.com/deepseek-ai/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 状态和冻结专长计算白名单：证据阶段只能读取通用证据规则、冲突规则、证据契约和当前专长检查项；写作阶段只能读取写作协议、分析/校验策略、文档契约和当前模板。所有读取会写入账本，必需数据集或资源未读全时拒绝推进或提交。

## 工作方式

```mermaid
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`；扫描内部还注册综合上下文、无损分页、单产物暂存与最终发布工具，更深层的分析能力会继续复用同一个服务边界。

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

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

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

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

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

```text
/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`。批次执行期间禁止修改绑定的系统事实，后续由独立系统单写者复核并在必要时生成新的系统版本。

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

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

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

## 当前系统级扫描产物

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

```text
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`](./docs/brand.md)。

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

```bash
command -v codebase-memory-mcp
```

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

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

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

## 插件架构方向

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

```text
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`](https://github.com/topics/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](LICENSE) 开源。

## 致谢

- [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)：提供“Everything is a Plugin”的 Agent Harness 与 Cordis 插件运行时。

---

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