内容
# 幻象
**幻象** 是 [Claude 代码](https://claude.com/claude-code) 的一个启动提示，用于将一个空的（或混乱的）仓库变成一个功能齐全、有自己意见的多智能体开发环境，只需一个命令即可完成。
它不是一个一次性安装后就可以忘记的工具。它是一个**可重复运行的规范**：每次你调用 `/phanes`，它都会重新扫描项目，升级现有的子代理，填充缺失的基础设施，并增加一个隐藏的运行计数器。其结果是一个智能生态系统，它随着代码库的演变而发展，而不是随着代码库的腐烂。
**所有内容都在一个文件中。** 整个系统是一个 Markdown 文件（`phanes.md`）；它依赖的每个脚本、钩子、代理和文档都是由运行本身生成的，在你的仓库内。
**你需要哪个文件？**
| 你的情况 | 使用 |
| --- | --- |
| 新项目，或一个没有幻象的项目 | **`phanes.md`** → `/phanes` 进行完整的引导。重新运行它也可以在安装最新版本的同时保持升级。 |
| 项目已经包含一个**较旧**的幻象（例如，v1 安装） | **`PhanesUpdateExperimental.md`** → `/phanesupdate` 进行版本迁移。 ⚠️ **实验性，迁移分支合并后效果不可逆转，需要强制备份（参见下面的“迁移较旧的安装”）。** 它首先从此仓库刷新您的 `/phanes` 命令，以便您迁移到最新的规范，然后在严格的、生成的、逐项验证的检查清单后面升级项目的整个幻象结构（代理、脚本、钩子、工作流、文档树）。累计知识（会话摘要、二级注释、快照）被保留和索引，不会重写。 |
**内容**
- [它做什么](#它做什么)
- [如何使用](#如何使用)
- [幻象强制的核心原则](#幻象强制的核心原则)
- [对于没有经验的用户：从零开始的逐步指南](#对于没有经验的用户从零开始的逐步指南)
- [如何安装](#如何安装)
- [迁移较旧的安装（实验性）](#迁移较旧的安装实验性)
- [配套工具](#配套工具)
- [版本](#版本) · [许可证](#许可证) · [贡献](#贡献)
---
## 它做什么
当你在仓库中第一次运行 `/phanes` 时，提示驱动 Claude 代码通过严格的多阶段设置：
1. **飞行前检查。** 安装它受益的三个 MCP 服务器：`context7`（实时库文档按需）、`deepwiki`（关于外部 GitHub 依赖的摘要答案，以便代理永远不会将依赖源拉入上下文）和 `serena`（符号级代码导航）通过 `uv`，如果缺少，它也会安装它们。这些是增强功能，而不是硬依赖；如果安装失败，它会被记录为待办事项，运行会继续降级而不是停止。确切地说是三个，刻意为之：MCP 工具模式每会话都会消耗上下文，因此每个生成的代理都带有使用费率，说明每个服务器何时节省代币，何时不进行 MCP 调用。平台首先被检测：POSIX 上的 bash，Windows 上的 PowerShell。
2. **仓库理解。** 读取 README、源树、配置和 CI，以推断项目的**真正**目的、主要语言、构建系统和模块边界。过滤掉无关目录（供应商依赖、示例包、演示内容）。
3. **项目内存基础设施。** 为每个子代理构建其运行的基础：
- `documentation/`：会话摘要、计划、日期架构快照和两层 API 注册表（第一层生成，第二层精选注释）。每个文件夹都有一个**生成的 `_index.md`**，因此代理通过降序索引（几百个代币）而不是扫描树来定位知识。文件遵守 500 行的软上限，如果超过，则会拆分并索引。
- `tests/`：`unit/`、`integration/`、`e2e/`、`fixtures/`、`helpers/`，带有逐字 README 和与 `src/` 相同的 `phanes new-file` 头戳规则。
- `.phanes/scripts/`：一个脚本库，拥有**所有**机械规则，从带有头戳和行检查的文件创建到文档上限审计 (`doc-check`)、索引再生 (`doc-index`)、注册表再生、API 差异和模块列表。
- **`.claude/settings.json` 钩子**：在工具层强制执行的机械规则。阻塞的 PreToolUse 守护进程拒绝创建未加戳的新文件， advisory PostToolUse 检查在每次写入时运行大小和文档审计。提示在上下文压力下会忘记；钩子不会。
- `.phanes/config.json`：确认的模块列表、语言、构建系统、钩子首选项。
4. **分层工作流定义。** 每个任务都被分诊到 T1（单文件快速修复）、T2（单模块功能）或 T3（跨切）。每个层级加载不同的上下文并使用不同的代理链，但**审查是普遍的**：即使是 T1 修复也会经过轻量级的 Critic 审查；只有审查深度和文档权重会根据层级缩放。任务中途升级需要停止并询问编排器。
5. **子代理团队生成。** 6-10 个深度范围的、世界级的角色写入 `.claude/agents/*.md`，每个角色由一个按日期的规则分配模型，该规则在每次更新运行时重新验证：
- **架构师/设计师**，**唯一**的二级注册表和架构快照编写者。
- **api-monitor**，**唯一**的一级注册表编写者；它在每次结构更改后运行。
- **批评代理**，生成编号的、ID 标签的审计报告。
- **补丁作者**，将综合的、批准的计划转化为顺序补丁文件，但绝不应用它们。
- **执行者**，仅应用批准的差异，并为每个新文件使用 `phanes new-file`。
- **合成器/仲裁者**，将并行视角的输出合并为一个统一的计划。
- 另外还有分析师、计划师、验证者、优化器、集成商、监控器和清洁剂等变体，根据您的特定堆栈进行调整。
- **侦察员** 不是团队代理：专家会临时创建它们作为**只读**子代理，获取和消化大量的临时上下文（模块调查、测试日志、注册表扫描），由严格的成本守护者管理，以便每次创建都能自筹资金。
6. **工作流编纂。** `.claude/workflows/` YAML 是链条的唯一真实来源；每个链条都以合成器（仅并行工作）→ 批评者 → `api-monitor`（T2/T3）→ 主代理结束，以便应用的工件始终是经过审计的工件。`CLAUDE.md`（仅项目根目录和模块根目录）会更新，以便主代理知道如何分诊、委托、导航索引文档和审查。
7. **引导会话摘要。** `documentation/session-summaries/SS00001_phanes-bootstrap_<date>.md` 记录安装、确认的模块列表、代理团队和任何延迟的待办事项。
> **第一次运行后：重启你的 Claude 代码会话。** 钩子配置在会话开始时快照，因此强制钩子在**下一个**会话中生效。幻象在运行结束时会明确提醒你这一点。
重新运行会通过 `.claude/.phanes` 标记检测现有的安装并在原地升级：代理、工作流、脚本、钩子和 README 会针对 `phanes.md` 的最新版本进行评估，并在有变化时刷新。通过 v1 创建的安装会被检测并路由到实验更新器（参见 [迁移较旧的安装](#迁移较旧的安装实验性)）。
## 如何使用
### 首次运行
在你的项目中输入 `/phanes`。它会扫描仓库并围绕它建立整个代理团队和文档结构。两件事能使首次运行成功：
- **给它一些可读的内容。** 在空或全新的仓库中，创建一个至少包含 `plan.md`，描述你想要构建的内容。幻象会读取它以了解项目的目的，并围绕你实际要构建的项目（而不是空文件夹）塑造整个设置（代理、工作流、模块布局）。
- **引导它，如果你愿意。** 命令后立即输入的任何内容都被视为指令，并优先于默认值，因此你可以将个别需求注入设置：`/phanes focus on the api/ module; skip pre-commit hook install`。
当运行完成时，**重启你的 Claude 代码会话** 以使强制钩子生效（幻象会提醒你）。
### 重新运行 `/phanes`：何时以及如何频繁运行
把 `/phanes` 视为**刷新 Claude 对你的项目的了解**：每次运行都会重新扫描代码库，并使代理团队、工作流和注册表与现实保持一致。
- **早期，小项目：自由运行。** 每天几次都没问题。在代码库较小的时候，一次运行的成本很低，代币和上下文消耗也很低，保持代理团队的更新换代会不断产生回报。
- **在实施计划之前**（一个好的软策略，而不是规则）：编写实施计划（例如，为新模块），然后运行 `/phanes` 并注入计划。注入意味着提示计划的内容（或其路径）后立即提示，幻象会更新代理和工作流，在需要时创建新的代理和工作流，以便团队能够完美地执行该计划。
- **会话边界。** 在一天结束时运行，或在开始工作时，可以保持项目上下文新鲜，以便在实际工作开始前启动。
- **大型项目：降低频率。** 一旦代码库较大，每天一两次即可。根据需要添加运行；较大的实施计划前添加运行；较小的计划通常不需要。
## 幻象强制的核心原则
- **脚本中的程序，提示中的判断，钩子在工具层。** 脚本可以强制执行的任何规则（行限制、头戳、注册表编辑、API 差异、文档上限）都位于 `.phanes/scripts/` 中；两个 `settings.json` 钩子使关键规则不可跳过。提示在上下文压力下会忘记；脚本不会；钩子不会被忘记。
- **每个工件只有一个编写者。** 每个注册表层、快照和摘要都有一个编写代理，每个生成的 `_index.md` 也是如此（`phanes doc-index` 是其唯一编写者）。许多读取者，一个编写者。
- **子代理不会直接修改代码。** 编码代理会发出包含建议差异的报告；批评者会审查它；执行者会应用它。审查深度会根据层级缩放；它的存在永远不会被豁免。主 Claude 代码代理也不会直接编辑代码；它会编排。
- **上下文注入优于上下文继承。** 子代理仅接收其层级允许的上下文切片，并通过只读侦察员摘要拉取大量材料，而不是加载原始材料。来自兄弟任务的污染在结构上是不可能的。
- **基于索引的文档导航。** 没有代理会批量读取 `documentation/`：索引会下降，目标会加载，其他的则不会。
---
## 对于没有经验的用户：从零开始的逐步指南
以前从未使用过 Claude？这将帮助你从零开始安装幻象。经验丰富的 Claude 代码用户可以直接跳到 ["如何安装"](#如何安装)。
### 步骤 1：创建 Claude 账户
前往 [claude.ai](https://claude.ai) 并注册（电子邮件或 Google 账户）。
### 步骤 2：获取可以承载幻象的计划
幻象是一个多智能体系统：单个任务可以运行多个 Claude 实例链（计划器、编码器、批评者、执行者、监控器），每个实例都会消耗使用额度。**Pro 计划将不足以应对**；它的限制在几个链条后就会耗尽。你需要以下之一：
- **Claude Max 5x**，适用于较轻项目的可行入口点。
- **Claude Max 20x**（推荐），具有足够的余量用于真正的多智能体工作。在 claude.ai 的“设置 → 计划”下订阅。
- **Claude API（按令牌支付）**：在 [console.anthropic.com](https://console.anthropic.com) 上创建帐户，添加积分，并注意多智能体编排比单聊使用更多的令牌；成本会根据驱动程度而增加。
（在官方页面查看当前定价；计划和限制会发生变化。）
### 步骤 3：安装 Claude 代码
**macOS / Linux：**
```bash
curl -fsSL https://claude.ai/install.sh | bash
```
**Windows（PowerShell）：**
```powershell
irm https://claude.ai/install.ps1 | iex
```
（替代方案：`npm install -g @anthropic-ai/claude-code` 如果您已经使用 Node.js 18+。）还请确保 `git` 已安装（[git-scm.com](https://git-scm.com)）；幻象需要它。
通过以下命令验证：
```bash
claude --version
```
### 步骤 4：登录
在任意项目文件夹中打开终端，运行 `claude` 并按照提示登录（或输入 `/login`）：选择 **Claude 账户** 如果您订阅了 Max，或 **Anthropic Console** 如果您通过 API 按令牌支付。
### 步骤 5：安装幻象
继续阅读下面的["如何安装"](#如何安装)。只有两个命令。
---
## 如何安装
幻象是一个单独的 Markdown 文件（`phanes.md`），因此安装只是将其放在 Claude 代码可以作为斜杠命令调用的位置。
### 先决条件
- [Claude 代码](https://claude.com/claude-code) 已安装并认证。
- `git`，以及您的项目实际使用的语言工具链。
- **Windows：PowerShell**（5.1 或更新版本，随 Windows 交付）；第 0 阶段的飞行前检查通过 PowerShell 运行；POSIX 系统使用任何标准 shell。
- 可选但强烈推荐：`uv`（用于 `serena` MCP 服务器）。如果缺少，0 阶段的飞行前检查将为您安装它。
### 作为用户级斜杠命令安装（推荐）
这使得 `/phanes` 在您打开的每个仓库中可用。
**Linux / macOS：**
```bash
mkdir -p ~/.claude/commands
curl -L https://raw.githubusercontent.com/Aloim/phanes/main/phanes.md \
-o ~/.claude/commands/phanes.md
```
**Windows（PowerShell）：**
```powershell
New-Item -ItemType Directory -Force "$env:USERPROFILE\.claude\commands" | Out-Null
Invoke-WebRequest `
-Uri https://raw.githubusercontent.com/Aloim/phanes/main/phanes.md `
-OutFile "$env:USERPROFILE\.claude\commands\phanes.md"
```
### 按项目安装（替代方案）
如果您只想在单个仓库中使用幻象并将其跟踪到版本控制中：
```bash
mkdir -p .claude/commands
curl -L https://raw.githubusercontent.com/Aloim/phanes/main/phanes.md \
-o .claude/commands/phanes.md
```
### 运行它
打开目标仓库中的 Claude 代码，然后输入：
```
/phanes
```
可选参数通过 `$ARGUMENTS` 传递并优先于默认计划，因此您可以引导运行：
/phanes focus on the api/ module; skip pre-commit hook install
首次运行需要几分钟，会暂停以确认几个选择（模块边界、钩子安装），并通过要求您重启会话以使强制钩子生效而结束。后续运行速度更快；只会写入差异。
### 首次运行后创建的内容
```
documentation/ # 会话摘要、计划、快照、注册表；每个文件夹都索引到一个生成的 _index.md
tests/ # 单元、集成、e2e、fixtures、helpers
.phanes/ # 脚本（new-file、regen-registry、api-diff、loc-check、doc-check、doc-index、hook-*）和配置
.claude/agents/ # 生成的子代理定义（6-10，深度范围）
.claude/workflows/ # 编纂的多智能体工作流（YAML，链条的唯一真实来源）
.claude/settings.json # 合并的钩子条目：钩子戳守护进程（阻塞）+ 钩子大小检查（建议）
.claude/template/ # 每个子代理使用的 report.md 模板
.claude/.phanes # 运行计数器和安装状态标记（隐藏）
CLAUDE.md # 根：主代理指令；模块根：文件夹特定指导
CLAUDE.local.md # 项目中正在进行的项目注册表（按约定 gitignored）
```
`.claude/`、`.phanes/` 和其他运行时工件被此仓库提供的默认 `.gitignore` 排除。根据需要在您自己的项目中进行调整。
---
## 迁移较旧的安装（实验性）
> ⚠️ **PhanesUpdate 是实验性的。它未经验证适用于现实世界的安装；迁移分支合并后效果不可逆转。** 开始之前：提交或暂存所有内容，将您的仓库推送到远程（或复制项目文件夹的完整副本），然后仅在您可以从备份恢复的项目上继续。提示拒绝启动，直到您确认这一点。
如果项目已经包含预 v2.0 的幻象安装，请在在在本地仓库中安装了较旧的幻象安装，请在 `/phanes` 旁边安装更新器：
**Linux / macOS：
```bash
curl -L https://raw.githubusercontent.com/Aloim/phanes/main/PhanesUpdateExperimental.md \
-o ~/.claude/commands/phanesupdate.md
```
**Windows（PowerShell）：**
```powershell
Invoke-WebRequest `
-Uri https://raw.githubusercontent.com/Aloim/phanes/main/PhanesUpdateExperimental.md `
-OutFile "$env:USERPROFILE\.claude\commands\phanesupdate.md"
```
然后**备份您的项目**，打开它并运行 `/phanesupdate`。它会自我更新您的 `/phanes` 命令，从此仓库指纹安装版本，并在专用分支上迁移结构，通过生成的、证据验证的检查清单进行。保留的工件会被存档，不会被删除。您自己审查和合并分支；**验证它是否正确，然后再合并，因为合并是无返回点的。**
---
## 配套工具
- **[Charon](https://github.com/Aloim/charon)** 查找死代码、未使用的文件、未使用的依赖项和重复代码，然后编写有证据支持的审计报告，而不触及任何内容。它是一个独立的 `/charon` 命令，可在任何仓库中使用；在幻象管理的项目中，它还会与幻象构建的结构合作：报告被提交到文档树中，打开的项目被纳入会话摘要，死亡的导出 API 被提议为注册表注释，以便代理团队停止将新工作路由到它们上。建议在大型重构和大型迁移后使用，因为静态代码是代理的上下文毒素。
---
## 版本
当前：**v2.1**（2026-07-10）。请参阅 `phanes.md` 顶部的版本戳。完整的发布历史：[`Changelog.md`](Changelog.md)。上一个发布的版本原样保留在 [`older version/phanes.md`](older%20version/phanes.md)。
---
## 许可证
幻象在 **知识共享署名-非商业性使用4.0国际许可** 下发布（参见 [`LICENSE`](LICENSE)）。
您可以自由地以署名为条件，将幻象用于任何**非商业**目的。商业使用不受此许可的授予；如需商业许可，请直接联系作者。
---
## 贡献
欢迎提出问题和拉取请求。对 `phanes.md` 的重大更改应解释**哪一类故障模式**该更改解决了：幻象是一个防御性文档，每个子句都承载负载。
