aimship 0.1.0-preview.11 → 0.1.0-preview.13

package/docs/guide.zh-CN.md

@@ -2,242 +2,408 @@
 
 [English](guide.md) · [README](../README.zh-CN.md)
 
-本指南按实际使用场景说明：需要提供什么，Agent 如何推进，以及在哪里查看成果。你不需要记住阶段名称或固定提示词。
+[交付目录](#delivery-structure) · [1. 使用示例](#start) · [2. 会话与续接](#guide-sessions) · [3. 需求输入与变更](#guide-inputs) · [4. 代码与多需求管理](#guide-projects) · [5. 问题处理与维护](#troubleshoot)
 
-<a id="install"></a>
-尚未安装时，先阅读 README 的[安装说明](../README.zh-CN.md#install)。
+<a id="24-查看当前工作"></a>
+<a id="44-交付目录与文档"></a>
+<a id="results"></a>
+<a id="3-查看进度与成果"></a>
+<a id="4-查看进度与成果"></a>
+<a id="4-查看进度与验收成果"></a>
+<a id="查看当前工作"></a>
+<a id="artifacts"></a>
+<a id="keep-only-useful-artifacts"></a>
+<a id="相关参考"></a>
+<a id="附录sql-与工程版本"></a>
+<a id="document-details"></a>
+<a id="sql变更和进度"></a>
+<a id="sql-与工程版本"></a>
+<a id="delivery-structure"></a>
+<a id="阶段产物与内容"></a>
+<a id="交付目录与文档"></a>
+<a id="固定大纲和可追溯编号"></a>
+<a id="guide-directory"></a>
 
-[选择 Aimship](#hosts) · [不同场景下如何开始](#start) · [推进与审核](#review) · [查看进度与成果](#results) · [需求变化](#changes) · [会话与续接](#continue) · [并行需求](#parallel) · [完成交付](#completion) · [使用问题](#troubleshoot)
+## 交付目录速览
 
-<a id="hosts"></a>
-<a id="1-在宿主中选择-aimship"></a>
-<a id="1-在-ai-开发工具中选择-aimship"></a>
-## 1. 在 AI 工具中选择 Aimship
+默认资料根目录为用户主目录下的 `~/Aimship/`，安装时另有配置则沿用。**每次交付在该根目录下独立存放，以 AI 回执中的实际路径为准**；需要另存时请明确说明。
 
-安装后开启新的 AI 工具会话，选择 Aimship：
+在 AI 工具项目空间中开展交付，空间中同时访问原有材料和 Aimship 交付目录：
 
-| AI 工具 | 如何选择 | 未显示时 |
-| --- | --- | --- |
-| Codex | 在 Skill 选择器中选择 Aimship；CLI 中使用 `$aimship` | 新建会话或重启 CLI，列表未刷新时重启应用 |
-| Cursor | 使用 `/aimship` | 新建 Agent 会话，检查 Customize → Skills；列表未刷新时重启 Cursor |
-| Claude Code | 使用 `/aimship` | 新建会话并检查斜杠命令列表；列表未刷新时重启 Claude Code |
+```text
+AI 工具项目空间
+├── 用户已有项目材料（按实际情况提供，保留原位置）
+│   ├── 原型、PRD、其他参考文档（如已有）
+│   └── 项目代码（如已有）
+└── Aimship 初始化生成的本次需求交付目录
+    └── 添加原目录 → ~/Aimship/20261027-login-signup/
+```
+
+按下方[启用并提出诉求](#guide-setup)完成初始化，收到实际路径后，将该交付文件夹（本例为 `20261027-login-signup`）添加到当前 AI 工具项目空间，或授予该目录的访问权限，后续在这个空间继续交付。已有项目材料按需要提供访问，不由 Aimship 初始化创建。目录名仅为示例，无需提前手工创建，也不要复制整份交付或在项目空间另建一套。
 
-每个 AI 工具分别需要登录、可用模型以及交付资料和相关代码仓库的访问权限，在实际操作需要时授权。交付资料单独保存，代码仍在原仓库中。
+该交付目录中的材料如下：
+
+```text
+~/Aimship/                         # 资料根目录
+└── 20261027-login-signup/          # 示例交付目录
+    ├── status.md                  # 当前工作、待审材料、下一步
+    ├── source/request.md          # 原始诉求
+    ├── prd.md                     # 需求与验收标准
+    ├── prototype/index.html       # 页面交互原型
+    ├── tech-design.md             # 技术方案
+    ├── openapi.yaml               # HTTP 接口契约
+    ├── database.sql               # 本例单数据库变更
+    ├── testing.md                 # 用例与后续执行结果
+    ├── plan.md                    # 实施任务与进度
+    ├── review.md                  # 各批及整体审查
+    └── handoff.md                 # 成果与交接说明
+```
 
-AI 工具集成仍处于实验阶段，真实 Skill 发现、目录访问和跨工具接续仍待验证。安装文件健康不等于 AI 工具已加载 Skill。Codex 和 Cursor 共用入口，兼容 AI 工具也可能发现其他位置的入口；出现重复项时检查路径和版本，保留无关或定制内容。AI 工具行为可参考官方 [Cursor 文档](https://cursor.com/docs/skills)和 [Codex Skill 位置说明](https://learn.chatgpt.com/docs/build-skills)。
+这些材料逐步形成，按需保留。正文中的 REQ、AC、TC 等编号可直接搜索，跨文档沿用对应编号，不要求锚点跳转。外部权威需求由 `scope.md` 承接，重要变更记入 `change-log.md`，独立调查才使用 `diagnosis.md`。查看进度先打开 `status.md`；需求修改或验收意见直接告诉 AI。
 
+<a id="1-开始与推进"></a>
 <a id="start"></a>
 <a id="需求依据与输入条件"></a>
 <a id="describe-the-work-and-its-endpoint"></a>
-## 2. 不同场景下如何开始
+<a id="2-不同场景下如何开始"></a>
+<a id="1-首次使用"></a>
+<a id="guide-example"></a>
+<a id="1-登录注册功能一次交付示例"></a>
+
+<a id="1-aimship-交付演示"></a>
+
+## 1. Aimship 使用示例
+
+以登录注册功能演示从需求到验收。**这是虚构实践参考，措辞和业务方案无需照抄。** 本例稍后提供工程和隔离测试数据库，约定需求后确认原型，再做技术设计；实际原型安排按交付需要确定。
+
+同一会话沿用一个 Aimship 入口，批准后按安排继续，无需逐阶段调用。需要你审核时，AI 会逐份展示材料并等待明确结论；修改后重新送审。
+
+<a id="11-准备工作位置"></a>
+<a id="12-启用-aimship-并说明需求"></a>
+<a id="13-确认保存结果并回答必要问题"></a>
+<a id="准备工作位置"></a>
+<a id="hosts"></a>
+<a id="1-在宿主中选择-aimship"></a>
+<a id="1-在-ai-开发工具中选择-aimship"></a>
+<a id="1-在-ai-工具中选择-aimship"></a>
+<a id="启用-aimship-并说明需求"></a>
+<a id="确认保存结果并回答必要问题"></a>
+<a id="install"></a>
+<a id="尚未形成需求文档"></a>
+<a id="guide-setup"></a>
 
-明确启用后，有具体问题或预期变化即可开始。Agent 保留相关原话和可见讨论，判断新建还是续接已有交付，复用当前可访问的工作空间。缺少访问权限时，会说明资料的具体路径和需要你完成的操作。代码可以稍后准备；项目空间名称本身不证明目录可访问。
+### 1.1 启用并提出诉求
 
-初始化保存 `source/request.md`、结构化状态和生成的 `status.md`。回执说明实际保存内容、位置、绑定的 Aimship 版本、代码关联情况、当前工作和下一步。PRD／Scope 在形成实质需求草稿时创建。终点、交互、接口或数据库条件未明确时保留未知；“先聊需求”不等于“只交付需求”，也不授予实施权限。
+**用户操作**：明确使用 Aimship，并说明目标。例如：
 
-普通讨论中途转入时，明确要求使用 Aimship 处理刚才的诉求。Agent 采用当前可见的相关输入，说明不可见历史的缺口，不重复询问已有答案，不把建议写成决定。若尚未保存就必须换会话，带上 Agent 给出的未保存上下文和计划位置，在新会话再次明确启用 Aimship。
+> 使用 Aimship，做用户名密码注册、登录、退出和登录后首页。完成开发与本地验证，不部署；代码稍后提供。
 
-代码准备好后，提供可访问的本地工程位置。Agent 读取必要规范和工程事实，关联到同一次交付。需求结论依赖既有行为时，可以在需求阶段读代码。关联不会克隆、搬动或修改代码，也不授予实施权限；新事实影响原决定时沿用现有变更流程。
+已有原型、PRD 或其他文档时，提供原位置即可，原件保留，用户无需手动复制。AI 按来源规则将正式采用的版本及必要依赖资源留存为本次交付 `source/` 中的副本，并记录采用依据；仅作背景参考的材料无需全量复制。后续修改先明确编辑对象，新版不覆盖旧依据。
 
-重复启用会续接同一身份和审核停点。回执中断或进度页失败时，Agent 核对实际保存结果并修复缺失视图，不重建交付或覆盖资料。归属不清时才澄清。新会话按[续接说明](#continue)明确启用并定位原交付；仅碰巧提及 Aimship 不会启用它。
+**AI 处理**：确定交付目录并核对访问，保留诉求，建立或续接交付，告知实际保存目录、当前工作和下一步。若无法访问，提示你添加该原目录或授权；不会改存到项目空间。
 
-### 尚未形成需求文档
+**输出产物**：`source/request.md` 保存原话；`status.md` 显示进度。新建交付时，AI 优先按明确偏好，否则按当前交流语言保存本次交付语言；状态和新文档沿用，文件名、编号、来源原文及已有文档不变。
 
-说明想解决的问题、使用者、期望变化和已知限制。有截图、讨论记录或参考资料时一起提供，无需先准备完整 PRD。
+<a id="14-阅读文档并给出结论"></a>
+<a id="15-批准后继续推进"></a>
+<a id="review"></a>
+<a id="逐份审核与自动衔接"></a>
+<a id="3-推进与审核"></a>
+<a id="2-审核并推进工作"></a>
+<a id="阅读文档并给出结论"></a>
+<a id="批准后继续推进"></a>
+<a id="guide-requirements"></a>
+<a id="guide-prototype"></a>
+<a id="12-确认需求与验收标准"></a>
+<a id="13-确认页面与交互原型"></a>
 
-初始化后，Agent 会澄清目标、范围和验收判断中的缺口，整理需求与验收标准，并说明后续工作安排。你确认目标和重要取舍后，Agent 继续推进。需求与验收标准通常记录在 `prd.md`，当前进度从 `status.md` 查看。
+### 1.2 确认需求
 
-### 已有 PRD、原型或其他资料
+**用户操作**：按已有材料提供输入。
 
-提供资料位置、准备采用的版本，以及相关代码位置；如果只采用部分内容，说明本次范围。已有资料不完整时，可以直接说明已知缺口。
+- 没有 PRD／原型：说明功能和预期行为，如“用户名不能重复，退出后再进首页必须登录”。
+- 已有材料：给出 PRD／原型的位置、版本和本次采用范围；只有部分材料也直接说明。
 
-Agent 会核对资料是否可访问、是否覆盖本次目标。采用权威 PRD／原型时，保留原件，通过 `scope.md` 记录采用范围、缺口和决定；零散参考则用于编写需求。已有交互被充分覆盖时复用，未覆盖的变化再补充。你可从需求文档和关联资料中查看采用了哪些内容、还需决定什么。
+分别打开送审的需求文档和适用原型，核对范围、验收标准及页面行为。每次对当前一份明确通过，或指出要修改的内容。
 
-### 修改现有功能、修复缺陷或重构
+**AI 处理**：澄清缺口；外部权威原件保留，覆盖充分的原型复用。无材料时先写需求，批准后按本例安排制作所需原型；无交互变化则不新增。逐份自检、送审，批准后保存再继续。
 
-提供相关仓库和功能位置，说明期望行为、当前问题及必须保留的行为。修复缺陷时附上可用的复现条件、错误信息或日志；重构时说明技术目标和不能改变的外部行为。
+**输出产物**：`prd.md` 说明需求与验收标准，或 `scope.md` 记录外部材料的采用范围；本例新建 `prototype/index.html` 展示页面与反馈状态。原型不代表认证已实现，未实际检查的交互仍标明未验证。
 
-Agent 会检查相关实现，确认需求与技术约束，安排设计、实施、审核和验证。普通调试随当前工作处理；重大未知问题需要独立调查时，再调整安排。`plan.md` 记录实施进度，`review.md` 和 `testing.md` 分别记录审核与实际验证结果。
+<a id="guide-session-example"></a>
 
-外部材料按采用版本保留原件，链接本身未必保留版本，访问缺口应明确。只有你明确委托维护现有可编辑 PRD，且它完整表达本次范围、授权和终点时，才登记复用；不能仅凭“以前由我们编写”就修改采用的原件。
+**换会话示例**：本例需求与原型通过并保存后，停止旧会话写入，在新会话明确启用：
 
-以上场景都由 Agent 保留原始委托并维护交付记录。重要的业务、范围、兼容性、成本或数据决策由你决定；授权内的日常技术取舍由 Agent 处理。待决问题没有回应时不会被视为批准，相关依赖工作等待解决。
+> 使用 Aimship 继续「实际交付目录」的登录注册交付，先读取状态、已批准材料和待审核停点。
 
-<a id="review"></a>
-<a id="逐份审核与自动衔接"></a>
-## 3. 推进与审核
+AI 重新核对同一交付目录的访问，读取状态并确认下一步技术设计；若仍有待审材料就停在那里，不重建或要求重述全部背景。也可留在原会话继续。
 
-标准主线是需求和验收标准 → 技术设计及适用的接口／SQL／交互产物 → 测试用例 → 实施计划 → 分批实施（含批内 review）→ 整体 review → 测试验证 → 交付验收。Agent 根据需求落实这条主线，不要求你逐项勾选核心阶段；无关产物不生成，已有正式材料先核对采用，采用不等于批准。
+<a id="guide-design"></a>
+<a id="14-审核技术方案"></a>
 
-每份需人审文档生成、自检后，Agent 展示当前阶段状态、文档入口和审核重点，等待你明确通过或提出问题。讨论、沉默和要求看结果都不算批准；修改后自检并重新送审。待审期间不提前提供下一阶段的续接提示。
+### 1.3 审核技术方案
 
-你明确通过后，Agent 在一次处理中记录批准及文档版本、保存进度和下一步、检查保存结果，再给出下一步建议。无需分别确认保存或提示词；保存失败时会如实说明。同一建议会话组内直接衔接下一项，不再询问是否开始；到组间边界则建议新会话并给出简短入口，本轮不同时执行下一阶段。你说“在当前会话继续”即可直接继续，不增加审批，具体见[会话划分建议](#continue)。
+**用户操作**：提供工程位置及已知测试条件；打开方案，检查密码保护、登录状态、访问控制和数据变更，明确通过或反馈。
 
-如果你明确不要测试用例和测试，Agent 会一次说明并记录范围，完成授权的开发与 review 后交接**未测试的阶段性成果**，不会偷偷补做或反复劝说。阶段性范围完成不等于标准完整交付完成，也不能写成验证通过。文档批准与最终交付验收分别记录。
+**AI 处理**：读取工程，核对技术条件，设计实现方式及风险处理；缺少关键事实先补齐，方案批准后准备接口与 SQL。
 
-授权内的实施、批内检查／修复和复测可继续推进；review 或测试发现问题时先修复或按既有规则回流。新增实质决定和生产动作仍需对应授权。
+**输出产物**：`tech-design.md` 说明怎样实现及取舍。此时设计后续 SQL，不要求 SQL 文件已经完成。
 
-<a id="results"></a>
-<a id="3-查看进度与成果"></a>
-## 4. 查看进度与成果
+<a id="guide-contracts"></a>
+<a id="15-逐份审核接口与-sql"></a>
 
-从交付目录的 **`status.md`** 查看当前阶段、待审文档、审核状态、阻塞事项、下一阶段和成果入口。查看验证结论时，同时关注对应版本、环境和证据。缺少账号、工具或环境的检查会标为阻塞或未执行，不能计为通过。
+### 1.4 逐份审核接口与 SQL
 
-<a id="delivery-structure"></a>
-<a id="阶段产物与内容"></a>
-### 交付目录与文档
+**用户操作**：接口送审时检查请求、响应、错误与登录要求；SQL 送审时检查目标库、结构、变更顺序及执行条件，分别通过或要求修改。
 
-默认每个需求在 `~/Aimship/` 下使用独立交付目录，代码保留在原仓库。
+**AI 处理**：依据已批准方案准备适用文档，逐份自检并等待审核；全部通过后进入测试设计。已有权威契约复用，无对应变更不生成文件，多数据库分别提供 SQL。
 
-下方列出交付产物及其用途；实际生成范围由约定交付范围和产物条件确定，无关工作不生成空文档。`prd.md` 与 `scope.md` 是需求入口的两种选择，并非每个需求都要同时生成。
+**输出产物**：本例 `openapi.yaml` 约定 HTTP 接口，`database.sql` 描述单库变更。**文档批准不授权执行 SQL 或修改迁移机制。**
 
-```text
-~/Aimship/
-├── 20261023-订单导出/             # 每个需求一个独立交付目录
-│   ├── status.md                 # 自动生成的进度总览和阅读入口
-│   ├── prd.md                    # 自编需求：目标、范围、需求和验收标准
-│   ├── scope.md                  # 采用权威外部资料时使用，替代自编 PRD
-│   ├── tech-design.md            # 技术方案：架构、改动、数据、风险和需求覆盖
-│   ├── plan.md                   # 实施计划：批次、任务及实际执行记录
-│   ├── testing.md                # 测试用例、覆盖关系、执行与重测结果
-│   ├── review.md                 # 各批及整体审核、发现的问题和处理结论
-│   ├── handoff.md                # 交付结果、使用方式、验证结论和遗留事项
-│   ├── diagnosis.md              # 仅独立调查时生成的定位与证据记录
-│   ├── change-log.md             # 重要变更、决定及受影响的工作
-│   ├── openapi.yaml              # 新建 HTTP 契约；已有权威契约优先复用
-│   ├── database.sql              # 单数据库 SQL；多目标为 database-<id>.sql
-│   ├── prototype/                # 符合生成条件时新建的原型
-│   │   └── index.html            # HTML 原型入口，相关资源也放在此目录
-│   ├── source/                   # 保留原始需求和采用的外部资料版本
-│   │   ├── request.md            # 原始委托或来源入口
-│   │   └── …                     # 外部 PRD、原型、截图及其他输入
-│   └── .aimship/                 # 工具维护的内部状态与辅助证据
-│       ├── state.json            # 阶段、引用、版本及仓库／worktree 关联
-│       ├── state.previous.json   # 写入后用于恢复的上一版状态
-│       ├── view.json             # 进度视图的生成元信息
-│       └── evidence/             # 按需保留的验证等证据
-└── 20261024-另一个需求/           # 独立的资料与进度
-```
+<a id="guide-cases"></a>
+<a id="16-审核测试用例"></a>
 
-正式文档直接放在需求目录下；`source/` 保留采用的原件，`.aimship/` 保存内部记录。软件安装目录为 `~/.aimship/`，与各需求目录内的 `.aimship/` 分别管理。
+### 1.5 审核测试用例
 
-<a id="固定大纲和可追溯编号"></a>
-需求、验收标准、实施任务、审核和测试结果之间的关联由 Agent 维护，便于追溯。
+**用户操作**：打开用例，核对正常注册登录、重复用户名、错误密码、未登录访问及退出后访问的预期结果；通过或指出遗漏。
 
-<a id="changes"></a>
-<a id="review-verify-and-change"></a>
-<a id="4-推进中需求发生变化"></a>
-## 5. 推进中需求发生变化
+**AI 处理**：将验收标准转为可检查的用例，注明环境与覆盖范围；用例批准后制定实施计划。
+
+**输出产物**：`testing.md` 的用例部分。这时还没有测试执行结果。
+
+<a id="guide-plan"></a>
+<a id="17-审核实施计划"></a>
+
+### 1.6 审核实施计划
+
+**用户操作**：打开计划，核对改动范围、任务依赖、分批与验证安排；通过或反馈。
+
+**AI 处理**：按工程依赖拆任务，如先完成认证与会话，再接页面和访问限制，安排测试代码及审查；计划与必要文档批准后才实施，单批也需要计划。
+
+**输出产物**：`plan.md` 说明各批做什么、依赖什么、如何检查。
+
+<a id="guide-implement"></a>
+<a id="18-分批实施与批内-review"></a>
+
+### 1.7 分批实施与批内 review
 
-说明发生了什么变化、原因以及希望保留的内容。如果已修改正式文档，指出位置，让 Agent 核对修改的含义。
+**用户操作**：查看改动和进度，有偏离及时指出，如“注册成功后的跳转与原型不一致”。无需逐条批准执行日志。
 
-Agent 会分析对范围、设计、实现和验证的影响，记录决定，更新受影响的工作安排和文档。需要你判断的取舍会提出，其他授权内工作继续，原始采用资料继续保留。
+**AI 处理**：按计划写代码，每批完成后审查并处理阻碍推进的问题，再进入下一批。全部批次完成后做整体审查，再统一验证；需求变化回到相应审核。
 
-已批准文档发生实质变更时，回到对应阶段重审，依赖它的工作等待审核解决后再继续；旧批准和结果保留为历史，不能用旧批准放行新版。重审通过后，按依赖顺序恢复。无关工作不重置，排版和错字修正不需全量重审。
+**输出产物**：工程代码；`plan.md` 追加执行进度，`review.md` 记录本批问题与修复。
 
-重要变化及影响记录在 `change-log.md`，后续安排从 `status.md` 查看。不要通过修改 `status.md` 来改变需求或表示验收；它是生成视图，已有手改内容需先保留，再由 Agent 核对和重建。
+<a id="guide-overall"></a>
+<a id="19-整体-review"></a>
 
+### 1.8 整体 review
+
+**用户操作**：查看整体结论和遗留问题，必要时指出遗漏；不需要为每条审查记录另做文档批准。
+
+**AI 处理**：检查全部实际改动及注册、登录、退出、首页访问的跨批衔接，处理阻碍验证的问题后进入独立验证。单批可用一份 review 明确覆盖批内及整体范围。
+
+**输出产物**：`review.md` 追加整体审查结论。代码审查不能代替运行测试。
+
+<a id="guide-verify"></a>
+<a id="110-执行验证并处理失败"></a>
+
+### 1.9 执行验证并处理失败
+
+**用户操作**：提供约定的隔离测试环境，查看执行结果，补充复现信息或缺失条件；另需授权的操作先明确目标与动作。
+
+**AI 处理**：对已 review 的代码执行用例，分别记录通过、失败、未执行。缺陷修复后审查并复测，保留失败历史；需求或设计问题回到相应材料。
+
+**输出产物**：同一 `testing.md` 追加实际代码、环境、结果与证据。缺少必要验证时如实列出，不写成通过。
+
+<a id="25-验收交付成果"></a>
+<a id="completion"></a>
+<a id="decide-when-work-is-done"></a>
+<a id="7-完成交付"></a>
+<a id="8-完成交付"></a>
+<a id="验收交付成果"></a>
+<a id="guide-handoff"></a>
+<a id="111-查看成果并验收"></a>
+
+### 1.10 查看成果并验收
+
+**用户操作**：按交接说明检查功能，符合目标后明确“验收通过”；有差异就说明实际与预期。
+
+**AI 处理**：汇总成果与遗留事项，记录你的实际验收决定。完整交付需有必要文档批准、批内及整体 review、独立验证和最终验收依据。
+
+**输出产物**：`handoff.md` 提供成果位置、用法、验证结论和合并／部署状态。先前文档批准不替代最终验收，开发完成也不等于已部署。
+
+<a id="guide-sessions"></a>
+
+## 2. 会话与续接
+
+<a id="2-会话进度与验收"></a>
+<a id="21-在新会话中接续"></a>
+<a id="23-会话划分建议"></a>
 <a id="continue"></a>
 <a id="continue-in-another-conversation"></a>
 <a id="5-暂停后或换会话继续"></a>
 <a id="6-暂停后或换会话继续"></a>
-## 6. 会话安排与继续工作
+<a id="6-会话安排与继续工作"></a>
+<a id="继续已有交付或切换会话"></a>
+<a id="3-下次如何继续"></a>
+<a id="安排新会话与交接"></a>
+<a id="在新会话中接续"></a>
+<a id="会话划分建议"></a>
+<a id="guide-continue"></a>
+<a id="21-换会话与接续"></a>
 
-### 会话划分建议
+### 2.1 何时换会话
 
-以下安排基于实际项目中的使用经验，可按任务规模调整。交付初建或需求确认时，Agent 会将适用的建议分组记录在状态中，并显示在 `status.md`：
+按 `status.md` 的建议在需求、技术与适用契约、用例、计划、实施批次、整体 review、验证批次之间换会话，也可继续当前会话；分组不改变逐份审核。
 
-| 工作内容 | 会话安排 |
-| --- | --- |
-| 需求／Scope | 一个会话 |
-| 技术文档、SQL、接口文档 | 共用一个会话 |
-| 测试用例设计 | 一个会话 |
-| 实施计划 | 一个会话 |
-| 实施 | 每个实施批次一个会话，包含该批 Agent 评审 |
-| 整体 review | 一个会话 |
-| 测试执行 | 每个测试批次一个会话 |
+新会话操作见[演示中的续接示例](#guide-session-example)。同一交付只保留一个写入会话；可信记录可直接定位，找不到或有多个候选才询问。交付语言沿用已保存设置。首次保存前就要切换时，携带未保存诉求、计划位置及未完成操作。
 
-这是使用经验，不是强制会话划分规则或阶段完成条件。可按任务规模、资料量和上下文累积情况调整；合并后的效果需在实际工作中核对。技术文档、SQL 和接口共用会话时，仍按既定顺序先审技术文档，再逐份审核适用的接口／SQL 文档，不能因为共用会话而跳过审核。
+<a id="22-工作意外停止后继续"></a>
+<a id="工作意外停止后继续"></a>
+<a id="guide-recovery"></a>
+<a id="32-中断重复启用或进度不一致"></a>
 
-实施批次与测试批次承担不同工作。测试批次按验证安排划分，不要求与实施批次一一对应，也不要求每个实施批次结束后立即测试。新会话本身不保证判断独立或质量；每个新会话仍需读取相关的完整正式文档、已保存状态和实际成果，不能只靠简短聊天摘要接手。
+### 2.2 中断后恢复
 
-### 安排新会话与交接
+提供原交付目录、中断时的操作和错误信息。AI 核对已保存状态、文件与未完成操作，保留身份及资料；状态已保存但进度页失败时只修复缺失视图。重复启用不重新初始化。
 
-到建议会话边界，Agent 先确认批准、成果和状态已保存，再说明当前成果与下一步，建议新会话并提供一行可复制入口，其中使用真实交付目录：
+进度页手改内容先保留，冲突先协调；不要靠改进度页表达批准。工程搬迁后提供新位置，由 AI 核对身份再更新关联。
 
-> 使用 Aimship 继续交付「实际目录」，先读取当前状态和相关正式文档再接续。
+<a id="3-其他起点与工作安排"></a>
+<a id="scenarios"></a>
+<a id="5-其他起点与工作安排"></a>
+<a id="guide-other"></a>
+<a id="2-其他使用说明"></a>
+<a id="guide-inputs"></a>
 
-你无需每次批准时再强调要换会话，也无需分别确认保存或生成提示词。可以直接回复“在当前会话继续”；会话划分只是上下文建议，不是审批或阻塞条件。最后交付结束时不提供无意义的下一阶段入口。需要完整提示词时可以提出，默认不逐阶段输出长提示词，也不新建提示词或交接文件。
+## 3. 需求输入与变更
 
-Aimship 本身不创建新会话。等当前会话确认保存并停止写入后，在 AI 工具中开启新会话，选择 Aimship 并粘贴入口。新会话必须唯一定位同一交付，核对实际状态、文档审批版本、相关完整正式文档、实际成果和未完成操作，再确定行动。已有可信绑定时不重复索要路径；没有明确绑定或有多个候选时会询问目录，不能猜“最近一个”。单说“继续下一阶段”或复制旧提示词不会形成新的批准，待审草案换会话仍然待审。
+<a id="31-已有-prd原型或其他资料"></a>
+<a id="已有-prd原型或其他资料"></a>
+<a id="guide-adoption"></a>
+<a id="23-已有-prd原型或其他资料"></a>
+<a id="33-将当前讨论转为交付"></a>
+<a id="将当前讨论转为交付"></a>
+<a id="guide-discussion"></a>
+<a id="25-从已有讨论转入"></a>
 
-同一交付只保留一个写入会话。代码位置和访问权限仍需可用，不能因换会话绕过审核或受影响工作的停点。进度始终从同一份 `status.md` 查看，无需复制完整聊天。
+### 3.1 已有资料或讨论
+
+提供 PRD、原型或截图的位置、版本和本次使用范围，AI 按[确认需求](#guide-requirements)核对。若要直接维护已有 PRD，请明确说明；AI 核对本次目标和完成范围后送审，已有文件不等于已批准。
+
+已有讨论可说：“使用 Aimship 继续刚才讨论的需求。”AI 整理可见的诉求、决定和待确认问题；看不到的历史请补充，建议不算批准。
+
+<a id="16-已批准的需求发生变化"></a>
+<a id="5-推进中需求发生变化"></a>
+<a id="changes"></a>
+<a id="review-verify-and-change"></a>
+<a id="4-推进中需求发生变化"></a>
+<a id="已批准的需求发生变化"></a>
+<a id="guide-changes"></a>
+<a id="22-已批准内容需要变化"></a>
 
-### 工作意外停止后继续
+### 3.2 修改已批准内容
 
-如果 Agent 因断网、工具退出或操作取消而停止工作，告诉它停止时正在处理什么，并提供已有错误信息。继续前，Agent 会核对实际文件、已保存进度及未完成操作，确认哪些操作已经完成，避免重复写入或重跑有副作用的动作。
+说明改什么、为什么改、哪些保持不变；自行改过文档时指出文件。AI 在 `change-log.md` 记录重要变化，将受影响文档重新送审，相关工作待确认后继续。未受影响的工作、旧批准和测试历史保留。
 
-代码仓库搬迁后提供新位置，由 Agent 核对身份后更新关联。状态冲突或进度视图异常需要先协调或修复，不能强行覆盖。
+新诉求写入需求文档和变更记录，不覆盖 `source/request.md`。原始诉求被误改时，从可靠原件恢复；找不到就暂停核对。错字或排版无需全部重审。交付后的小修可继续原交付；新目标或大幅重设计另建交付，并注明与原交付的关系。
 
-### 升级 Aimship 后继续已有交付
+<a id="guide-limits"></a>
+<a id="27-只做到部分目标"></a>
 
-升级 Aimship 后，旧会话可能保留旧规则。先保存工作，再让 Agent 在稳定边界核对当前版本与交付记录；无法可靠刷新时开启新会话。旧格式交付需要明确迁移、采用规则并整理相关文档后继续，未知格式保持只读。已有原件和历史结果保留，不补造过去未执行的工作，也不将旧完成记录当作批准；恢复协议供 Agent 查阅 [CLI 文档](cli.md)。
+### 3.3 只完成部分目标
 
+本次只需需求、设计或明确不做测试时，请说明。AI 记录做到哪里及未覆盖的部分，交接时标明阶段性成果，未测试不写成通过。“先看预览”不会改变原定目标。
+
+独立调查才使用 `diagnosis.md`；普通调试不增加调查阶段。
+
+<a id="guide-projects"></a>
+
+## 4. 代码与多需求管理
+
+<a id="32-修改现有功能修复缺陷或重构"></a>
+<a id="34-需求开始后再关联代码"></a>
+<a id="修改现有功能修复缺陷或重构"></a>
+<a id="需求开始后再关联代码"></a>
+<a id="guide-code"></a>
+<a id="24-修改已有代码或稍后关联代码"></a>
+
+### 4.1 关联代码、修复或重构
+
+提供代码目录，例如：“代码在「工程目录」，继续当前交付。”AI 沿用原交付目录和审核记录，需要了解现有功能时可先只读查看；实际修改仍按约定范围进行。新发现影响已批准内容时重新送审。远端地址不会触发自动克隆或搬迁。
+
+修复缺陷时，提供预期表现、实际问题、复现步骤或日志。重构时，说明改善目标和必须保持不变的功能行为。
+
+<a id="35-同时推进多个需求"></a>
+<a id="7-同时推进多个需求"></a>
 <a id="parallel"></a>
 <a id="work-on-two-requests-at-once"></a>
 <a id="6-同时推进多个需求"></a>
-## 7. 同时推进多个需求
+<a id="同时推进多个需求"></a>
+<a id="guide-parallel"></a>
+<a id="26-同时处理多个需求"></a>
 
-不同需求使用独立交付目录，每个交付只保留一个写入会话。向 Agent 说明已知的共享代码、接口、数据库或测试环境。
+### 4.2 同时处理多个需求
 
-一个需求正在修改代码时，另一个可以先做只读分析。两个需求都要修改同一份代码之前，安排串行实施或独立 checkout／worktree，并优先复用已有隔离。Agent 会根据可访问的已知交付记录核对重叠范围，在计划中记录协调方式；未知或过期记录、Aimship 外的工作不在完整掌握范围内。
+每个需求使用独立交付目录，并说明共用的代码、接口、数据库或环境。可以同时分析；修改同一份代码时安排先后，或使用独立工作目录并安排合并。
 
-各需求分别查看自己的进度和结果。分支完成不代表集成完成；Aimship 不提供全局锁、自动 Agent 调度、自动创建 worktree 或自动合并。
+AI 只能核对已知且可访问的交付，不会自动锁定或调度其他会话。请说明其他正在进行的修改，各自完成后仍需检查合并结果。
 
-<a id="completion"></a>
-<a id="decide-when-work-is-done"></a>
-<a id="7-完成交付"></a>
-## 8. 完成交付
+<a id="4-常见问题与参考"></a>
+<a id="troubleshoot"></a>
+<a id="8-使用中遇到问题"></a>
+<a id="9-使用中遇到问题"></a>
+<a id="6-常见问题与参考"></a>
+<a id="guide-troubleshoot"></a>
+<a id="3-权限恢复与版本"></a>
+<a id="guide-maintenance"></a>
 
-查看交接记录中的成果位置、使用方式、审核和验证结论、遗留问题与后续事项，并对照原目标判断是否接受。
+## 5. 问题处理与维护
 
-Agent 会分别记录目标完成、用户验收、合并和部署的实际情况。要求预览不代表缩短目标；明确提前结束时，交接中保留原目标和未完成工作。
+<a id="41-常见问题"></a>
+<a id="guide-access"></a>
+<a id="31-工作位置与访问权限"></a>
 
-标准完整交付需要主线工作、必要文档批准、通过的批内／整体 review、独立验证及最终验收都有依据。`status.md` 将标准完整性与约定范围的完成、用户验收分别显示；工具核对记录，不能独立证明测试真实执行或内容正确。明确缩减范围的成果可完成并交接，但会显示为阶段性范围；未测试就明确写未测试。旧交付保留原完成和验收记录，先标为尚未按新标准评估，核对证据并明确采用新规则后再续接，不补造历史审批或测试。
+### 5.1 目录无法访问
 
-后续小修正可以继续原交付，并保留此前完成记录；新目标或大幅重新设计则建立关联的新交付。
+按 AI 报出的实际路径，在 AI 工具中添加原交付目录或授予所需权限。若目录尚未创建，按工具支持的方式授权所需父目录，再继续初始化。不要复制交付或换个位置另建一套。
 
-<a id="troubleshoot"></a>
-<a id="8-使用中遇到问题"></a>
-## 9. 使用中遇到问题
+能读文件不代表能保存；AI 应根据实际读写结果报告是否成功。Aimship 不会替你操作权限界面。尚未保存的诉求请保留在当前会话，恢复访问后先核对已有文件，再继续；安装不会自动创建交付目录或授予访问权限。
 
-| 情况 | 如何处理 |
-| --- | --- |
-| 无法访问资料或代码 | 在当前 AI 工具授权需要的目录，说明失败的具体操作，不通过搬动资料绕过权限限制 |
-| 进度页与实际成果不一致 | 请 Agent 核对当前记录和实际文件，保留手改内容后重建进度页 |
-| 正式文档在会话外被修改 | 指出修改位置，请 Agent 核对含义及对后续工作的影响 |
-| 旧交付无法继续 | 请 Agent 检查格式迁移、规则采用和文档整理，保留历史结果并说明阻塞原因 |
-| 找不到 Aimship、安装或版本异常 | 查看 README 的[安装与升级问题](../README.zh-CN.md#installation-troubleshooting) |
+<a id="43-ai-工具集成说明"></a>
+<a id="ai-工具集成说明"></a>
+<a id="guide-hosts-notes"></a>
+<a id="34-找不到入口或宿主行为不同"></a>
+<a id="34-找不到入口或-ai-工具行为不同"></a>
+<a id="guide-tools"></a>
 
-反馈问题时提供 AI 工具和 Aimship 版本、具体操作、预期与实际结果，以及可复现的最小资料；隐去凭据、个人路径和业务数据，通过 [GitHub Issues](https://github.com/clsx/aimship/issues)提交。
+### 5.2 找不到 Aimship 入口
 
-## 相关参考
+先按 README 检查安装状态，再尝试新开会话或刷新 AI 工具的 Skill 列表，明确选择 Aimship。具体入口以所用 AI 工具的版本和支持方式为准；安装检查通过不代表它已经加载 Skill。
 
-<a id="artifacts"></a>
-<a id="keep-only-useful-artifacts"></a>
-文件位置与用途见[交付目录与文档](#delivery-structure)；涉及数据库或工程版本时，可查阅附录中的 [SQL 与工程版本说明](#document-details)。
+出现重复入口时，先核对来源和版本，保留已有定制内容。Codex 与 Cursor 共用安装入口，不要直接删除重复项。真实 AI 工具的发现、权限和跨工具续接尚未完整验证；可参考 [Cursor 文档](https://cursor.com/docs/skills)和 [Codex Skill 位置说明](https://learn.chatgpt.com/docs/build-skills)。
+
+<a id="42-升级-aimship-后继续已有交付"></a>
+<a id="升级-aimship-后继续已有交付"></a>
+<a id="guide-upgrade"></a>
+<a id="33-升级后继续已有交付"></a>
 
+### 5.3 升级后继续
+
+升级前保存当前工作，再按 README [升级](../README.zh-CN.md#update)。升级后重新启用 Aimship，核对实际绑定版本和交付状态；安装本身不会更新交付记录。
+
+使用普通 Markdown 和可搜索编号记录交付。规则更新前核对影响，保留实际审批和测试记录，不补造结果。
+
+<a id="45-安装与维护参考"></a>
+<a id="安装与维护参考"></a>
 <a id="update"></a>
 <a id="update-or-stop-using-aimship"></a>
-软件升级、添加 AI 工具和版本／安装状态查询见 [README](../README.zh-CN.md#update)。
-
 <a id="uninstall"></a>
-断开 AI 工具或完整卸载见 [README](../README.zh-CN.md#uninstall)。源码开发与隔离验证见[贡献指南](../CONTRIBUTING.md)。
+<a id="guide-references"></a>
+<a id="35-安装维护与反馈"></a>
 
-<a id="document-details"></a>
-<a id="sql变更和进度"></a>
-## 附录：SQL 与工程版本
+### 5.4 安装维护与反馈
 
-SQL 标明目标、方言、版本／结构依据、执行条件，按顺序组织语句并关联需求和设计，在技术方案通过后的 contract 阶段、测试用例之前准备并逐份审核。Markdown 中的 SQL 片段或迁移文件引用不能替代它。生成 SQL 不代表获准执行数据库操作或修改工程迁移机制。
+安装、升级、添加 AI 工具、版本与健康查询见 [README](../README.zh-CN.md#update)，移除见[卸载说明](../README.zh-CN.md#uninstall)。健康查询只检查安装文件和配置，不会修复交付文档；安装中断或文件缺失时，按 README 对应问题处理，不盲目重装。
 
-已有工程 HTTP 契约继续作为权威来源，避免维护另一份相互冲突的副本。项目当前版本和目标版本在 PRD／Scope 中记录，并注明工程来源和观察依据；未设置版本时如实说明。`plan.md` 记录实际改动，审核与测试结果定位准确的 commit、构建或未提交内容。多仓库分别记录版本和对象引用，与 Aimship 规则版本、状态格式及保存 revision 区分。交接记录最终代码对象和真实合并／发布状态，目标版本不代表已发布版本。
+反馈时提供版本、操作、预期与实际结果，以及最少的复现步骤。隐去凭据、个人路径和业务数据后提交 [Issue](https://github.com/clsx/aimship/issues)。开发见[贡献指南](../CONTRIBUTING.md)，工具协议见 [CLI 文档](cli.md)。