APX默认项目：是草稿本，不是工作区

Agent 工具需要一个地方来存放没有归属项目的零散工作。APX 为此内置了 default 项目，路径在 ~/.apx/projects/default/。它让超级代理能够处理通用的、未限定范围的任务，而无需先要求用户创建仓库。

但这种便利暗藏风险：一旦 default 悄然变成真实项目工作的家，问题就会浮现。默认工作区跨上下文共享，没有仓库契约来承载意图，没有可提交的代理定义，也没有另一台机器能够接管的可移植边界。它是回退方案，不是所有权。

一条简单实用的规则：草稿工作用 default；当工作属于某个项目时，创建或注册一个 APC 项目。

草稿工作的典型场景

以下几种情况很适合放在默认项目里：

• 让 APX 解释一条命令、比较两个想法，或生成一份临时清单。
• 开启一段不依附于代码库、客户或团队的私人对话。
• 在决定某个模型或工具是否应进入项目之前，先做尝试。

这些操作需要本地运行时状态，但尚不需要持久的项目协议。一次对话记录、一个短期任务或一个实验，都可以留在 APX 本地。

边界何时改变？当工作开始需要共享规则、可重复的代理角色、可复用的技能，或需要版本控制中的审查时，它就已经具备项目形态，哪怕它还不是一个 Git 仓库。

APX 的运行时状态（对话记录、会话、任务日志、凭据、机器特定设置）本质上属于“本地状态”，与代码仓库或项目定义无关。它通常保存在 ~/.apx/projects/<apx_id>/ 这样的目录中，并由 APX 自身管理生命周期。与之相对，项目契约是“可移植状态”，应当能够随仓库一起被克隆、审查和迁移。理解这一区分有助于判断一项工作是否真的需要项目：如果它只产生运行时状态，默认项目就足够；如果它产生需要共享、审查或复用的契约，就应该放入 APC 项目。

为持久工作提供明确归属

APX 项目是一个包含 AGENTS.md 和 .apc/project.json 的目录。APC 文件承载可移植的项目上下文：代理定义、技能、MCP 提示和项目元数据。APX 注册该目录，并将仅运行时状态单独存储在 ~/.apx/projects/<apx_id>/ 下。

对于新项目，在其目录中启动：

apx init
apx project add .

对于已有的 APC 项目，仅注册即可：

apx project add /path/to/project

之后，当当前目录不可靠时，可以显式指定目标项目：

apx agent list --project my-project
apx exec reviewer --project my-project "Review the release notes"

这一选择回答了两个独立问题。APC 回答项目意味着什么、哪些指导可以随项目一起迁移。APX 回答本地对话、会话、任务日志、凭据和机器特定设置应该放在哪里。双方无需假装拥有对方。

APC（Agent Project Contract）是一种用于描述代理项目上下文的约定，通常以 .apc/project.json 文件为核心，承载代理定义、技能、MCP 提示和项目元数据。它不规定运行时如何执行，而是规定项目“意味着什么”以及哪些指导可以随项目迁移。APX 则负责注册 APC 项目目录，并管理本地运行时状态。两者分离的好处是：项目契约可以独立于任何一台机器存在，而运行时状态可以因机器而异，无需强行同步。

AGENTS.md 是放在项目根目录的说明文件，用于向代理描述项目结构、约定和操作指南。它通常被版本控制跟踪，因此队友克隆仓库后可以立即获得相同的代理指导。与 .apc/project.json 配合，AGENTS.md 提供人类可读的上下文，而 APC 文件提供机器可读的契约。两者共同构成 APX 识别项目边界的基础：一个目录只要包含这两个文件，就可以被 apx project add 注册为项目。

隐式所有权为何会带来麻烦

假设一个团队因为默认项目已经打开，就用它来做发布规划。计划在面板里看起来可用，但克隆仓库的队友无法从仓库中发现其规则或代理角色。随后，无关的私人聊天和项目历史又共享同一个运行时桶。上下文变得难以审查、迁移或安全清理。

将同样的工作放入 APC 项目，并不会让每次对话都变得可移植——也不应该如此。原始会话和私有运行时记忆仍然留在本地。真正迁移的是契约：项目指令、具名代理、可复用技能和安全的共享元数据。另一台机器可以注册该项目，并围绕该契约构建自己的本地运行时状态。

让回退方案保持可见

默认项目的价值恰恰在于它是临时的、无主的。不要删除它，也不要过度设计它。只需避免把需要持久边界的工作交给它。

当任务只是一个问题时，草稿区就够了。当任务需要队友、审查、可重复性或未来的检出时，给它一个项目目录和 APC 上下文。

回退方案让 APX 保持好用，显式项目让工作保持可理解。