# 项目、工作区与会话

> 选择任务的文件边界，管理连续对话，并用项目指令保持长期约束。

Canonical page: /core/workspaces-and-sessions



<Takeaways>
  <li>
    先选对项目，再开始会话
  </li>

  <li>
    长期规则写进 AGENTS.md
  </li>

  <li>
    删除列表、清空历史和删除目录是三件不同的事
  </li>
</Takeaways>

项目决定一组工作的本地目录和长期背景；会话记录一次连续任务的消息、工具调用和结果。先选对项目，再开始会话，可以减少路径错误和上下文混乱。

## 选择从哪里开始 [#选择从哪里开始]

<Entries>
  <Entry kicker="CHAT" title="对话">
    咨询、无需固定项目的临时任务。不自动绑定具体项目目录。
  </Entry>

  <Entry kicker="NEW" title="新建项目">
    在一个新目录中开始长期工作。文件边界是新项目目录。
  </Entry>

  <Entry kicker="OPEN" title="打开项目">
    让 Astravia 处理已有本地目录。文件边界是选择的目录。
  </Entry>

  <Entry kicker="SSH" title="从远程主机添加">
    让 Astravia 处理一台已登记 SSH 主机上的目录。命令和文件读写发生在那台机器上。
  </Entry>

  <Entry kicker="IMPORT" title="导入项目">
    恢复带 Astravia 会话和状态的项目包。文件边界是导入后的项目目录。
  </Entry>
</Entries>

需要读取、编辑或生成文件时，选择对应项目。只是讨论方案、起草短文本或查询信息时，可以从「对话」开始。

## 远程主机上的项目 [#远程主机上的项目]

本机目录之外，项目可以放在一台你本来就能用 `ssh` 连上的机器上。

1. 打开 **设置 → SSH 主机**，手动添加，或从 `~/.ssh/config` 导入别名。连接目标填终端里能连上的别名，或 `user@host`。
2. 添加项目时选择 **从远程主机添加**，再在那台机器上选目录。
3. 之后 Agent 的命令和文件读写都在那台主机上执行。会话里的终端也直接开在那台机器上，不必再自己开一个 ssh。

远程项目没有沙盒。沙盒只能约束这台电脑上的进程，而远程命令跑在远端。删除主机记录不会删除远端文件；如果上面还有项目，需要先移除那些项目。主机被删掉或重新添加后标识变了，项目会要求重新绑定，会话仍留在项目里。

## 项目与会话的关系 [#项目与会话的关系]

<Relationship aria-label="项目与会话关系">
  <RelationshipRoot>
    <strong>项目 / 工作区</strong>

    <span>目录、AGENTS.md、文件与产物</span>
  </RelationshipRoot>

  <RelationshipChildren>
    <div>
      <strong>会话 A</strong>

      <span>修复登录问题</span>
    </div>

    <div>
      <strong>会话 B</strong>

      <span>补充部署说明</span>
    </div>

    <div>
      <strong>会话 C</strong>

      <span>从 B 分叉验证另一方案</span>
    </div>
  </RelationshipChildren>
</Relationship>

<Beats>
  <li>
    一个项目可以有多个会话，它们共享项目目录，但各自保留对话和执行历史。
  </li>

  <li>
    新目标通常新建会话；继续同一目标时恢复原会话。
  </li>

  <li>
    分叉适合从既有上下文探索另一条路径，原会话不会被覆盖。
  </li>

  <li>
    从列表移除项目不会删除磁盘目录；「删除项目」会永久删除目录，必须仔细阅读确认信息。
  </li>
</Beats>

## 在消息旁单独提问 [#在消息旁单独提问]

阅读普通会话时，可选中一段文字，右键选择「问问 AI」。问答在小面板中进行，可以继续追问或停止回答。关闭面板后回答仍会继续，问题和回答自动保存。

保存过批注的消息会在悬停或键盘焦点时显示批注标记。点击标记可重新打开，并从批注面板搜索当前会话的问题和回答。

批注参考首次提问时截至原消息的文字上下文；已有压缩时使用摘要和后续记录，不读取图片内容或执行工具。它使用会话当前模型，独立产生模型用量，不增加普通会话，也不会将讨论写入主对话上下文。删除主会话会同时删除批注。

## 用项目指令保存长期约束 [#用项目指令保存长期约束]

项目详情页可以编辑 `AGENTS.md`。它适合保存所有会话都需要遵循的规则，例如技术栈、测试命令、目录所有权和禁止操作。

<Plate no="01" title="项目约束">
  ```markdown
  # 项目约束

  - 使用 Bun，不切换包管理器。
  - 修改认证模块后运行 `bun run test:auth`。
  - 不修改 `generated/`，它由构建脚本生成。
  ```
</Plate>

不要把一次性任务、密钥或个人临时信息写进项目指令。一次性要求放在当前消息中。

## 管理历史与产物 [#管理历史与产物]

<Beats>
  <li>
    侧栏展开项目即可查看最近会话，筛选器可区分普通、批量、对话和 Claw 会话。
  </li>

  <li>
    项目详情显示会话数量，并提供新会话、导出和活动面板入口。
  </li>

  <li>
    导出项目会包含项目文件、Astravia 会话历史和批量任务状态；文件锁会被排除。
  </li>

  <li>
    「清空会话」删除历史但保留产物；「清空产物」删除输出文件但保留会话，两者语义不同。
  </li>
</Beats>

<Callout type="warn" title="删除前先分清三种操作">
  「从列表移除」只改变 Astravia 列表；「清空会话」删除任务历史；「删除项目」会从磁盘永久删除整个目录。
</Callout>

## 推荐做法 [#推荐做法]

<Checklist title="长期使用时保持这些习惯">
  <li>
    一个稳定目录对应一个项目。
  </li>

  <li>
    一个清晰目标对应一个会话。
  </li>

  <li>
    长期规则写入 

    `AGENTS.md`

    ，本次验收写在任务消息里。
  </li>

  <li>
    需要比较方案时分叉，不在同一会话中来回覆盖目标。
  </li>

  <li>
    重要项目在破坏性操作前先使用项目导出或自己的版本控制。
  </li>
</Checklist>