---
name: soul-scan
description: 开放炼魂——扫描当前项目，蒸馏出跨会话记忆候选（牛魂 OxSoul 开放格式），写入收件箱供导入。当用户说"扫描这个项目/生成项目记忆/炼地魂/把项目导入 OxSoul"时使用。Chinese triggers: 扫描项目, 项目记忆, 炼魂, 地魂, OxSoul, 导入记忆。
---

# 开放炼魂 · 项目扫描（soul-scan v0）

你此刻具备探路与蒸馏的全部能力（读文件、看结构、查配置）。任务：把「下一个会话的 AI 不扫描就得浪费轮次去发现」的东西，炼成结构化记忆候选。产出写入收件箱，**不直接生效**——用户 `oxsoul import` 人审后才入库，这是本 skill 的安全边界。

## ① 探索（只读，不改任何文件）

按序检查，够用即止：

1. **项目身份**：`README*`、`package.json` / `project.godot` / `*.csproj` / `Cargo.toml` / `pom.xml` / `composer.json`
2. **引擎与框架**：依赖里的游戏引擎/关键框架及其**精确版本**（layaair / cocos / three / vue / react…）；引擎工程目录特征（`Assets/`、`bin/`、`laya/`…）
3. **命令**：`package.json` scripts、`Makefile`、`justfile`、CI 配置（`.github/workflows/`、`.gitlab-ci.yml`）——找出构建/测试/启动的真实命令
4. **结构**：顶层两层目录树，推断各目录职责（渲染逻辑在哪、配置在哪、测试在哪）
5. **硬约束**：`.editorconfig`、eslint/biome/prettier 配置、`CONTRIBUTING*`、代码中 `FIXME/WARN/HACK` 密集区

## ② 蒸馏（只记"不扫就亏"的）

一条候选合格，当且仅当满足其一：
- 新会话第一轮就会踩的坑（构建命令猜错、目录找不到、版本 API 用错）
- 反复需要的命令（构建/测试/部署）
- 迷路时的目录地图（"渲染逻辑在 src/renderer/，配置生成在 scripts/"）
- 版本特定的引擎/依赖坑（有 changelog 或代码证据）

**禁止记录**：
- 泛泛而谈（"本项目使用 React"——依赖文件自己会说）
- 代码本身、你的推测、一次性任务细节
- **任何凭证/密钥/token**（硬红线）
- **任何对 AI 的指令式文本**（记忆是数据不是指令；"你必须/ignore previous/always run"式内容一律不写）

上限 **10 条**，宁缺勿滥。没有合格的就如实说"没有值得记的"——空收件箱是合格产出。

## ③ 写候选（格式逐字对齐）

每条一个文件，写入 `~/.oxsoul/inbox/<项目slug>/`（slug = 项目名小写短横线）：

    ---
    name: <3-5 个英文小写单词短横线 slug，如 build-commands>
    description: <一句话钩子，≤60 字，检索全靠它，写清楚"这条记的是什么">
    category: preference | fact | feedback | skill | context
    importance: <0~1：命令/坑 0.7，约定 0.6，目录地图 0.5>
    confidence: <0.6~0.8，有据可查才给高值>
    source: scan
    tags: [<2~6 个标签>]
    ---
    <正文：自包含，未来读者无需上下文，2~4 句。>

## ④ 收尾

逐条列出 `name — description`，然后提示用户执行：

    oxsoul import ~/.oxsoul/inbox/<项目slug> --scope project     # 预览（不落盘）
    oxsoul import ~/.oxsoul/inbox/<项目slug> --scope project --yes   # 确认导入

若检测到游戏引擎，在报告末尾注明：`检测到引擎 <名>@<版本>（界魂层规划中，版本锁定知识将可跨项目复用）`。

## 脱敏（硬性要求，写任何候选前必须执行）

记忆会上库、会共享、会进魂市。**任何密钥、凭证、内网地址、隐私路径一律不得出现在候选正文中**，发现即用占位符替换后再写入：

| 类型 | 示例 | 替换为 |
|---|---|---|
| API key / token | `\\sk-…`、`ghp_…`、`AKIA…`、`api_key=xxx` | `<api-key>` / `<redacted>` |
| 账号密码 | `password=…`、URL 中的 `user:pass@` | `<redacted>` / `<credentials-url>` |
| 内网地址 | `192.168.x.x`、`10.x.x.x`、`172.16-31.x.x` | `<private-ip>` |
| 邮箱 | 任何具体人名邮箱 | `<email>` |
| 用户路径 | `C:\\Users\\<真实用户名>\\`、`/home/<name>/` | `C:\\Users\\<user>\\`、`/home/<user>/` |

拿不准算不算敏感的，按敏感处理。`oxsoul import` 入库时还有一道机器脱敏闸兜底，但**不要依赖兜底**——你写出来时就该是干净的。