Project Scanner — Prompt Template

Used by /understand Phase 1. Dispatch as a subagent with this full content as the prompt.

5 个模板分别对应 `/understand` 流水线的 Phase 1、2、4、5、6（project-scanner → Phase 1，file-analyzer → Phase 2，architecture-analyzer → Phase 4，tour-builder → Phase 5，graph-reviewer → Phase 6），**正文指令保持逐字不变**。这一点的工程意义在于：提示词本体是平台无关的纯文本，真正绑平台的只有外层调度壳。

### 当前仓库形态对照

观察当前仓库可以发现方案在落地后经过迭代：5 个 pipeline 文件仍保留在 [understand-anything-plugin/agents/](https://gitcode.com/GitHub_Trending/un/Understand-Anything/blob/ba450c43425f3de6d43daf76526950ad8ca93536/understand-anything-plugin/agents/?utm_source=gitcode_repo_files) 下，但其 frontmatter 已被精简为只含 `name` 与 `description`（见 [file-analyzer.md](https://gitcode.com/GitHub_Trending/un/Understand-Anything/blob/ba450c43425f3de6d43daf76526950ad8ca93536/understand-anything-plugin/agents/file-analyzer.md?utm_source=gitcode_repo_files)、[graph-reviewer.md](https://gitcode.com/GitHub_Trending/un/Understand-Anything/blob/ba450c43425f3de6d43daf76526950ad8ca93536/understand-anything-plugin/agents/graph-reviewer.md?utm_source=gitcode_repo_files)），`tools`/`model` 等平台绑定字段已被清除；同时 [SKILL.md](https://gitcode.com/GitHub_Trending/un/Understand-Anything/blob/ba450c43425f3de6d43daf76526950ad8ca93536/understand-anything-plugin/skills/understand/SKILL.md?utm_source=gitcode_repo_files) 目前编排为 0～7 共八个阶段的完整流水线。结论是：**"剥离平台相关 frontmatter、以纯提示词复用"这一设计意图最终保留并强化了**，而文件物理位置则在演进中重新收敛回 `agents/` 目录。

## Task 2：SKILL.md 调度改造——上下文注入模式

这是全计划技术含量最高的一步。设计文档点明了取舍动机：

> Reading templates through the main session adds ~11K tokens total (~5.5% of 200K context). This is sequential (one template at a time), and context compression reclaims earlier content. Acceptable trade-off for portability.

即：主会话依次读取各阶段模板再分发给子代理，全程只增加约 11K token（约占 200K 上下文的 5.5%），换来的是跨平台可移植性——**值得**。

改造后，调度措辞从"Dispatch the **project-scanner** agent with this prompt"统一变为"Dispatch a subagent using the prompt template at `./project-scanner-prompt.md`"，并在每次分发时**追加一段"来自主会话的额外上下文"**。计划逐 Phase 给出了注入蓝图，核心规律可归纳为下表：

| 阶段 | 注入内容 | 目的 |
|---|---|---|
| Phase 0 | 收集 `$README_CONTENT`（前 3000 字符）、`$MANIFEST_CONTENT`（package.json/pyproject.toml/Cargo.toml/go.mod/pom.xml）、`$DIR_TREE`（`find $PROJECT_ROOT -maxdepth 2 -type f \| head -100`）、`$ENTRY_POINT`（探测 `src/index.ts`、`main.py`、`main.go` 等常见入口） | 建立共享的"项目事实基线" |
| Phase 1 | 注入 README + manifest，并声明"README 与 manifest 是权威信息，优先于启发式推断" | 让项目名/描述/框架检测更准确 |
| Phase 2 | 注入项目名、描述、Phase 1 检测到的框架与语言，附带框架级角色指引（React/Next.js 的 `app/`、`components/` 是什么；Express 的 `routes/`、`middleware/` 怎么分类；Django 的 `views.py`/`models.py` 如何映射；Go 的 `cmd/`/`internal/`/`pkg/` 语义） | 让文件摘要与角色归类更准确 |
| Phase 4 | 注入框架提示与两级目录树，附带框架 → 架构层映射（如 `app/`→UI Layer、`routes/`→API Layer、`models/`→Data Layer），并声明"目录结构是分层边界的有力证据" | 让架构分层推断有据可依 |
| Phase 4 增量 | 复跑时注入上一轮 layer 定义，尽量保持层名与 ID 不变 | 保证增量更新的命名一致性 |
| Phase 5 | 注入 README（前 3000 字符）与检测到的入口点 | 让导览叙事与项目自述文档对齐，并从真实入口起步 |
| Phase 6 | 注入 Phase 1 的文件清单（`{path, sizeLines}`）与各阶段累积的 warning/error | 交叉校验：清单中每个文件都应存在对应 `file:` 节点，反向也要核对 `filePath` 是否都在清单内 |

此外 Error Handling 同步升级：任何子代理分发失败时**用同一提示词 + 失败上下文重试一次**；各阶段 warning 统一累积到 `$PHASE_WARNINGS` 列表，交给 Phase 6 做全量校验。计划 Step 9 还要求全文搜索 "Dispatch the **"，确保零残留的命名 agent 调度。

### 当前仓库形态对照

上下文注入模式在当前 [SKILL.md](https://gitcode.com/GitHub_Trending/un/Understand-Anything/blob/ba450c43425f3de6d43daf76526950ad8ca93536/understand-anything-plugin/skills/understand/SKILL.md?utm_source=gitcode_repo_files) 中完全落地并进一步强化。例如 Phase 1 现在要求 "Dispatch a subagent using the `project-scanner` agent definition (at `agents/project-scanner.md`). Append the following additional context:"，紧随其后就是大段的 "Additional context from main session"（对应行号约 [SKILL.md](https://gitcode.com/GitHub_Trending/un/Understand-Anything/blob/ba450c43425f3de6d43daf76526950ad8ca93536/understand-anything-plugin/skills/understand/SKILL.md?utm_source=gitcode_repo_files#L235-L268)）；Phase 4 在基础模板之外还增加了按检测语言读取 `./languages/<language-id>.md`、按检测框架读取 `./frameworks/<framework-id>.md` 追加注入的机制（[SKILL.md](https://gitcode.com/GitHub_Trending/un/Understand-Anything/blob/ba450c43425f3de6d43daf76526950ad8ca93536/understand-anything-plugin/skills/understand/SKILL.md?utm_source=gitcode_repo_files#L420-L437)）。可见原计划里"把 Phase 1 上下文作为权威依据注入"的思想，已经推广到语言级与框架级的上下文注入，且 `/understand` 已扩展为 7 阶段编排。

## Task 3：新增 knowledge-graph-guide 复用 agent

计划同时新增了一个与流水线解耦、可被任意 Skill 或用户直接调用的通用 agent，其 frontmatter 与职责在 [设计文档](https://gitcode.com/GitHub_Trending/un/Understand-Anything/blob/ba450c43425f3de6d43daf76526950ad8ca93536/docs/superpowers/specs/2026-03-18-multi-platform-simple-design.md?utm_source=gitcode_repo_files) 中被定义为：

```yaml
---
name: knowledge-graph-guide
description: |
  Use this agent when users need help understanding, querying, or working
  with an Understand-Anything knowledge graph. Guides users through graph
  structure, node/edge relationships, layer architecture, tours, and
  dashboard usage.
model: inherit
---

它被设计为"懂图谱 Schema 的向导"，需要掌握五类知识：

• 知识图谱 JSON 的顶层结构（version、project、nodes、edges、layers、tour）；
• 5 类节点与 18 类边的完整清单；
• 如何在 JSON 上定位、追踪节点与关系；
• 交互式 dashboard 的用法；
• 架构层与导览的解释方式。

计划还给出了图谱文件的标准位置：<project-root>/.understand-anything/knowledge-graph.json 与 meta.json。

当前仓库形态对照

该 agent 已在仓库落地为 knowledge-graph-guide.md。对比计划原型可看到知识体系随仓库演进显著扩充：节点类型从 5 类扩到 16 类（5 类代码节点 file/function/class/module/concept，8 类非代码节点 config/document/service/table/endpoint/pipeline/schema/resource，3 类领域图节点 domain/flow/step）；边类型从 18 类扩到 29 类、7 个类别（新增 Infrastructure 与 Domain 两组）；图谱存储也从 .understand-anything/ 演进为"兼容旧目录，否则用新目录 .ua/"的双目录解析逻辑（UA_DIR="<project-root>/$([ -d ... ] && echo .understand-anything || echo .ua)"），并且新增了由 /understand-domain Skill 产出的 domain-graph.json。ID 约定也随之细化，例如非代码节点采用 service:<relative-path>、table:<relative-path>:<table-name> 等带路径前缀的格式。

Task 4：把平台安装文件移到仓库根目录

Claude Code 之外各平台对"Skill 目录"的发现位置各不相同：Codex 与 OpenClaw 通过符号链接暴露到用户级 Skill 目录，OpenCode 通过插件配置注册，Cursor 通过 .cursor/plugins/。为了让这些平台在 clone 仓库后能自动发现安装指引，计划将三个平台的 INSTALL.md 从插件包装目录迁到仓库根目录：

understand-anything-plugin/.codex/INSTALL.md    →  .codex/INSTALL.md
understand-anything-plugin/.opencode/INSTALL.md →  .opencode/INSTALL.md
understand-anything-plugin/.openclaw/INSTALL.md →  .openclaw/INSTALL.md
understand-anything-plugin/.cursor/INSTALL.md   →  删除（由 .cursor-plugin/plugin.json 取代）

迁移后用 git mv 保留历史、再删除被取代的 .cursor/ 目录。计划特别强调：各 INSTALL.md 里的符号链接目标仍指向 understand-anything-plugin/skills——因为 skills 目录仍留在插件包装内部，这些链接保持有效。

交互模型非常轻量：用户只需给 AI 一句话"Fetch and follow instructions from …/INSTALL.md"，AI 便会自动完成 git clone 与符号链接/插件配置。这就是设计原则中"AI-driven installation"的落地形态。

当前仓库形态对照

后续演进中该模式被进一步统一：当前仓库根目录已不再散落各平台 INSTALL.md，而是收敛为两个跨平台安装器 install.sh（macOS/Linux）与 install.ps1（Windows）。按 README.md 的说明，install.sh <platform> 会把仓库 clone 到 ~/.understand-anything/repo，再为所选平台创建正确的符号链接，支持 codex、opencode、openclaw、gemini、pi、vscode、kiro 等十余种平台值，并提供 --update 与 --uninstall <platform> 选项。README 还提示了一个易错点：各平台调用前缀不同，多数用斜杠命令 /understand，而 Codex 用 $ 前缀（$understand），否则直接以自然语言请求即可。"一份内容、AI 按平台执行安装"的核心理念被完整继承。

Task 5：为 Cursor 与 Claude 添加插件描述符

插件描述符（plugin descriptor）是实现"clone 即发现、无需手动安装"的关键。计划为两个平台各创建一个 JSON：

.cursor-plugin/plugin.json（计划原型，版本 1.0.5）：

{
  "name": "understand-anything",
  "displayName": "Understand Anything",
  "description": "AI-powered codebase understanding — analyze, visualize, and explain any project",
  "version": "1.0.5",
  "author": { "name": "Egonex" },
  "license": "MIT",
  "keywords": ["codebase-analysis", "knowledge-graph", "architecture", "onboarding", "dashboard"],
  "skills": "./understand-anything-plugin/skills/",
  "agents": "./understand-anything-plugin/agents/"
}

.claude-plugin/plugin.json 结构类似（无 displayName 与 skills/agents 指向）。计划特别注释了路径设计：由于源码仍嵌套在 understand-anything-plugin/ 中，描述符里 skills/agents 字段要显式指回该包装目录，Cursor 才能据此完成 skill 与 agent 的发现。

当前仓库形态对照

仓库根目录现有三份真实描述符，结构完全遵循该模式且版本已演进到 2.9.4：

• .cursor-plugin/plugin.json——含 displayName、homepage、repository、license: MIT 与指向包装目录的 "skills": "./understand-anything-plugin/skills/"、"agents": "./understand-anything-plugin/agents/"；
• .claude-plugin/plugin.json——精简版，供 Claude Code 市场机制读取；
• .copilot-plugin/plugin.json——同一模式向 VS Code + GitHub Copilot 的扩展。

配套的 .claude-plugin/marketplace.json 也在根目录存在，计划 Task 7 专门验证其 source 字段仍指向 ./understand-anything-plugin——说明插件包装目录的嵌套结构是刻意保留的稳定契约，描述符只是最外层的"发现入口"。

Task 6：README 多平台章节更新

文件移动必然导致旧链接失效。Task 6 要求把所有指向旧嵌套路径的 raw URL（…/understand-anything-plugin/.codex/INSTALL.md 等）批量更新为根目录新路径，并把 Cursor 安装说明整体替换为自动发现描述：

### Cursor

Cursor auto-discovers the plugin via `.cursor-plugin/plugin.json` when this repo is cloned.
No manual installation needed — just clone and open in Cursor.