aimship 0.1.0-preview.7 → 0.1.0-preview.8

package/docs/guide.zh-CN.md

@@ -2,276 +2,209 @@
 
 [English](guide.md) · [README](../README.zh-CN.md)
 
-本指南涵盖安装、使用和维护。交付目标与相关资料作为流程输入，交付记录由 Agent 随工作推进维护。
-
-[安装](#install) · [宿主设置](#hosts) · [开始需求](#start) · [文档与阶段](#artifacts) · [审核与变更](#changes) · [进度接续](#continue) · [并行需求](#parallel) · [升级](#update) · [卸载](#uninstall) · [排障](#troubleshoot) · [结束交付](#completion)
+本指南按实际使用场景说明：需要提供什么，Agent 如何推进，以及在哪里查看成果。你不需要记住阶段名称或固定提示词。
 
 <a id="install"></a>
-## 1. 安装 Aimship
-
-需要 **Node.js 22+ 和 npm**。安装与工具行为已在 macOS arm64、Node 24 和 26 上检查；Node 22 及其他操作系统仍待验证。以下命令使用 POSIX shell 写法。
-
-### 安装已发布的预览版
-
-```sh
-npx aimship@preview install --host codex
-```
-
-宿主可选 `codex`、`cursor` 或 `claude-code`。连接多个宿主时重复该选项：
-
-```sh
-npx aimship@preview install --host codex --host claude-code
-```
-
-按 npm 提示确认获取安装包。`@preview` 表示已发布的预览通道，也可以替换为明确版本号，例如 `@0.1.0-preview.7`。预览通道用于实验性版本，不代表稳定版。
-
-### 从源码或本地包安装
-
-在 Aimship 源码仓库中执行：
-
-```sh
-node bin/aimship.mjs install --host codex
-```
-
-使用 tarball 安装时，将 `VERSION` 替换为实际版本号，在包所在目录执行：
+尚未安装时，先阅读 README 的[安装说明](../README.zh-CN.md#install)。
 
-```sh
-npx --offline file:./aimship-VERSION.tgz install --host codex
-```
-
-这些方式运行的是同一套安装器，选择其中一种即可。不需要全局 npm 安装或管理员权限；本地包需要可写的 npm 缓存，不需要登录 npm。只有确实要安装到日常环境时才使用真实用户目录。
-
-### 软件与交付资料目录
-
-| 位置 | 用途 |
-| --- | --- |
-| `~/.aimship/` | 固定版本的软件、配置和自定义内容 |
-| `~/.aimship/bin/aimship.mjs` | 当前已安装版本的稳定入口 |
-| `~/Aimship/<需求>/` | 一个交付的文档及其内部 `.aimship/` 记录 |
-| 现有代码仓库 | 代码、分支和 worktree，通过交付状态关联 |
-
-安装不会新建空交付或搬动代码。首次安装可用 `--data-root` 指定资料根目录，后续安装保留已有配置。无需配置语言，也无需逐项目安装。安装器保留当前版本及最多一个普通恢复版本，遇到被修改或不属于它管理的文件会保留并报告。
-
-如需隔离试用，将提供的 tarball 放在当前目录，替换 `VERSION` 后执行：
-
-```sh
-trial=$(mktemp -d)
-trial=$(cd "$trial" && pwd -P)
-npx --yes --offline --cache "$trial/npm-cache" file:./aimship-VERSION.tgz install --home "$trial/home" --host codex
-node "$trial/home/.aimship/bin/aimship.mjs" --version
-node "$trial/home/.aimship/bin/aimship.mjs" status
-node "$trial/home/.aimship/bin/aimship.mjs" install --host cursor
-node "$trial/home/.aimship/bin/aimship.mjs" uninstall --host cursor
-node "$trial/home/.aimship/bin/aimship.mjs" uninstall
-```
-
-`--home` 只改变受管理安装文件的位置，不会让当前宿主自动发现这个目录或继承权限。安装后的稳定入口默认继续管理自己的安装目录。检查结束后可删除该临时目录，不要将其替换成真实用户目录。
+[选择 Aimship](#hosts) · [按当前情况开始](#start) · [推进与审核](#review) · [查看进度与成果](#results) · [需求变化](#changes) · [会话与续接](#continue) · [并行需求](#parallel) · [完成交付](#completion) · [使用问题](#troubleshoot)
 
 <a id="hosts"></a>
-## 2. 在宿主中选择 Aimship
+<a id="1-在宿主中选择-aimship"></a>
+<a id="1-在-ai-开发工具中选择-aimship"></a>
+## 1. 在 AI 工具中选择 Aimship
 
-| 宿主 | 管理的入口 | 显式调用 | 安装或变更后如何刷新 |
-| --- | --- | --- | --- |
-| Codex | `~/.agents/skills/aimship/` | 选择 Aimship；CLI 中用 `$aimship` | 新建会话或重启 CLI，检查实际 Skill 选择器；列表未刷新时重启应用 |
-| Cursor | 同一个 `.agents/skills/aimship/` 入口 | `/aimship` | 新建 Agent 会话，检查 Customize → Skills；列表未刷新时重启宿主 |
-| Claude Code | `~/.claude/skills/aimship/` | `/aimship` | 新建会话并检查斜杠命令；列表未刷新时重启宿主 |
+安装后开启新的 AI 工具会话，选择 Aimship：
 
-宿主集成仍处于实验阶段。真实环境中的发现、目录访问和跨宿主接续仍需验证。每个宿主分别需要登录、可用模型以及相关资料和代码根目录的访问权限。安装文件检查通过，不代表宿主已经加载 Skill。Aimship 不启用云同步。
-
-Codex 和 Cursor 共用一个管理入口。兼容宿主还可能发现其他位置的入口，因此“登记了宿主”和“宿主实际发现 Skill”是不同的事。如果出现重复项，先检查路径和版本，保留无关或定制过的入口。可参考官方 [Cursor 文档](https://cursor.com/docs/skills)和 [Codex Skill 位置说明](https://learn.chatgpt.com/docs/build-skills)。
-
-直接使用已安装版本添加宿主，并查看安装健康状态：
+| AI 工具 | 如何选择 | 未显示时 |
+| --- | --- | --- |
+| Codex | 在 Skill 选择器中选择 Aimship；CLI 中使用 `$aimship` | 新建会话或重启 CLI，列表未刷新时重启应用 |
+| Cursor | 使用 `/aimship` | 新建 Agent 会话，检查 Customize → Skills；列表未刷新时重启 Cursor |
+| Claude Code | 使用 `/aimship` | 新建会话并检查斜杠命令列表；列表未刷新时重启 Claude Code |
 
-```sh
-node "$HOME/.aimship/bin/aimship.mjs" install --host cursor
-node "$HOME/.aimship/bin/aimship.mjs" --version
-node "$HOME/.aimship/bin/aimship.mjs" status
-```
+每个 AI 工具分别需要登录、可用模型以及交付资料和相关代码仓库的访问权限，在实际操作需要时授权。交付资料单独保存，代码仍在原仓库中。
 
-CLI 的 `status` 命令查看软件安装状态；交付目录的 `status.md` 查看需求进度，两者用途不同。
+AI 工具集成仍处于实验阶段，真实 Skill 发现、目录访问和跨工具接续仍待验证。安装文件健康不等于 AI 工具已加载 Skill。Codex 和 Cursor 共用入口，兼容 AI 工具也可能发现其他位置的入口；出现重复项时检查路径和版本，保留无关或定制内容。AI 工具行为可参考官方 [Cursor 文档](https://cursor.com/docs/skills)和 [Codex Skill 位置说明](https://learn.chatgpt.com/docs/build-skills)。
 
 <a id="start"></a>
 <a id="describe-the-work-and-its-endpoint"></a>
-## 3. 交付目标与授权范围
+## 2. 按当前情况开始
 
-发起交付时，应明确预期成果、资料与代码位置，以及本次授权范围。无需预先准备完整 PRD：
+### 从一个想法开始
 
-> 使用 Aimship 增加订单导出功能。使用现有应用仓库和这些截图，完成实施、review 和验证，部署留到后续。
+说明想解决的问题、使用者、期望变化和已知限制。有截图、讨论记录或参考资料时一起提供，无需先准备完整 PRD。
 
-> 使用 Aimship 梳理通知偏好功能，产出需求、原型和技术方案，本次先不实施。
+Agent 会澄清影响范围和验收判断的缺口，整理需求，提出所需阶段及执行顺序。你确认目标和重要取舍后，Agent 继续推进。需求与验收标准通常记录在 `prd.md`，当前进度从 `status.md` 查看。
 
-Agent 在 `source/request.md` 保留原始委托，确定需求依据，并提出需要的阶段和顺序。安排被接受后，就按该顺序执行。重要的业务、范围、兼容性、成本或数据决策由你决定；授权内的日常工程取舍由 Agent 处理。没有回应不等于批准待决提案。
+### 已有 PRD、原型或其他资料
 
-仅做方案时可以不需要可写代码仓库。交付目录不必是宿主的主工作区，在实际操作需要时授权访问即可。Agent 不应为绕过访问限制擅自搬动资料。
+提供资料位置、准备采用的版本，以及相关代码位置；如果只采用部分内容，说明本次范围。已有资料不完整时，可以直接说明已知缺口。
 
-<a id="artifacts"></a>
-<a id="keep-only-useful-artifacts"></a>
-## 4. 文档、阶段和生成规则
+Agent 会核对资料是否可访问、是否覆盖本次目标。采用权威 PRD／原型时，保留原件，通过 `scope.md` 记录采用范围、缺口和决定；零散参考则用于编写需求。已有交互被充分覆盖时复用，未覆盖的变化再补充。你可从需求文档和关联资料中查看采用了哪些内容、还需决定什么。
 
-目录位置以 [README 的注释目录树](../README.zh-CN.md#交付目录与文档)为准：正式文档直接放在需求目录，新原型放在 `prototype/`，原始资料放在 `source/`，内部状态和证据放在 `.aimship/`。交付内不再增加 `docs/` 或 `sql/` 层级。
+### 修改现有功能、修复缺陷或重构
 
-### 需求依据与输入条件
+提供相关仓库和功能位置，说明期望行为、当前问题及必须保留的行为。修复缺陷时附上可用的复现条件、错误信息或日志；重构时说明技术目标和不能改变的外部行为。
 
-| 输入条件 | 需求文档 | 原型处理 |
-| --- | --- | --- |
-| 提供权威 PRD／原型供本次采用 | 用 `scope.md` 记录采用版本、本次范围、缺口、决定和验收，保留原件 | 已覆盖的交互复用；委托范围内有未覆盖的交互变化时补原型 |
-| 只有想法、讨论、截图或零散参考 | 自编 `prd.md`，其中包含范围和验收 | 委托范围内涉及交互变化、且现有材料未覆盖时生成原型 |
-| 技术重构或已知原因的修复 | 自编 `prd.md`，说明技术目标、边界、行为约束和验收 | 不涉及交互变化就不生成原型 |
-| 独立调查、只做 review 或只做验证 | PRD／Scope 只定义本次委托及终点 | 不虚构后续实施需求或原型 |
+Agent 会检查相关实现，确认需求与技术约束，安排设计、实施、审核和验证。普通调试随当前工作处理；重大未知问题需要独立调查时，再调整安排。`plan.md` 记录实施进度，`review.md` 和 `testing.md` 分别记录审核与实际验证结果。
 
-`prd.md` 和 `scope.md` 是需求依据的两种选择，不应默认同时创建两份重复描述。如果你明确委托维护一份已有、可编辑的权威 PRD，且它完整表达本次范围、授权和终点，可以登记复用。仅凭“以前由我们编写”不能认定采用的原件可以修改。
+以上场景都由 Agent 保留原始委托并维护交付记录。重要的业务、范围、兼容性、成本或数据决策由你决定；授权内的日常技术取舍由 Agent 处理。待决问题没有回应时不会被视为批准，相关依赖工作等待解决。
 
-外来的 PRD、原型、图片等按采用版本保留在 `source/`，自己生成的正式文档按上述位置存放。需求变化时不改写外部原件。单独一个链接未必能保留资料版本，Agent 应记录可用来源、版本和访问缺口。提取文本、查看视觉内容、操作原型和编辑原格式，是不同能力。
+<a id="review"></a>
+<a id="逐份审核与自动衔接"></a>
+## 3. 推进与审核
 
-### 阶段产物与内容
+通常的开发顺序是 PRD／Scope → 技术方案 → 接口和独立 SQL（适用时）→ 测试用例 → 实施计划 → 实施／评审／验证 → 交付验收。原型、调查和仅设计委托保留约定终点；仅 review、仅 verify 使用已有依据。
 
-阶段名称是稳定标识。下表是阶段目录，不是强制顺序；实际选用哪些阶段及其依赖，由接受后的执行安排决定。即使无需单独执行需求阶段，每次交付仍保留原始委托、需求／范围依据和状态记录。共用 `plan.md` 或 `testing.md` 不代表两个阶段同时完成，各阶段分别记录状态和结果。文档在对应阶段开始时形成草稿，文件已创建不等于阶段已完成。
+每份需人审文档生成、自检后，Agent 给出文档入口、短摘要和下一阶段，等待你审核。你阅读文档后提出修改意见，或明确表示通过。有修改意见时，Agent 修改、自检后再次送审。提问、沉默和要求看结果都不算批准。
 
-| 阶段 | 使用条件 | 产物及内容 |
-| --- | --- | --- |
-| `frame` 问题定义 | 问题或预期结果仍需澄清 | PRD／Scope 的目标与背景章节：问题、目标、非目标和假设 |
-| `requirements` 需求 | 需要编写或采用需求 | `prd.md`：目标、范围、需求、状态、验收和执行安排；或 `scope.md`：资料采用、本次范围、排除项、决定、验收和执行安排 |
-| `scope` 范围确认 | 需要明确本次委托边界 | 更新 PRD 的范围或 Scope 的目标／边界，不再新建另一份需求说明 |
-| `prototype` 原型 | 所需交互变化未被现有资料覆盖 | 新 HTML 使用 `prototype/index.html`，相关资源放在同目录；其他约定格式或复用入口单独登记 |
-| `diagnose` 调查定位 | 明确安排了独立调查 | `diagnosis.md`：目标、现象、环境、证据、原因、未知项和结论 |
-| `tech-design` 技术方案 | 需要设计技术实现 | `tech-design.md`：依据、架构、模块、数据／契约、异常、风险和需求覆盖；需要的 SQL 在该阶段结束前完成 |
-| `contract` 契约 | 需要新增或调整契约 | HTTP 使用 `openapi.yaml` 或已登记的工程权威契约；非 HTTP 契约登记约定格式 |
-| `plan` 实施计划 | 任何实施开始前，包括单个小批次 | `plan.md`：依据、批次、任务、验证安排、执行记录章节和剩余工作 |
-| `test-design` 测试设计 | 需要编写测试用例 | `testing.md`：依据、环境、用例／断言，以及需求和验收覆盖 |
-| `implement` 实施 | 执行已确定的计划 | 在代码仓库实施；同一份 `plan.md` 记录实际任务状态、代码对象和偏差 |
-| `review` 审核 | 审核某批、整体成果，或单独受托 review | `review.md`：审核依据、各次审核范围、发现与处理、结论 |
-| `verify` 验证 | 必要 review 后执行带版本用例，或单独受托验证 | 在同一份 `testing.md` 追加执行批次／RUN、实际结果、证据、重测和结论 |
-| `handoff` 交接 | 交付约定终点的成果 | `handoff.md`：目标、产物、使用方式、审核／验证结果、限制，以及完成／验收／集成状态 |
-
-开发流程中，`plan` 必须先于首次实施完成。每批实施后 review，全部完成后整体 review，再独立验证。实施时可以编写测试代码，但不额外设置逐批全量测试门禁。只有一批时，一次 review 可以明确覆盖批次和整体范围。单独委托验证时，可以采用已有、明确版本的用例，不声称重新执行过 `test-design`。
-
-普通开发调试、已知原因的 Bug 不增加 `diagnose`。实现错误回到实施，设计错误回到技术方案，需求缺口回到 PRD／Scope，错误的测试预期回到带版本的用例。出现需要独立调查的重大未知项时，应记录阶段调整，相关依赖工作暂停。
-
-### SQL、变更和进度
-
-| 产物 | 生成规则与内容 |
-| --- | --- |
-| `database.sql` | 数据库结构或数据发生变化时需要；一个数据库目标在需求根目录使用这一份文件 |
-| `database-<id>.sql` | 多个独立数据库目标各一份，`id` 使用稳定的目标标识 |
-| `change-log.md` | 有重要变更时记录原因、旧／新含义、决定、影响文档与工作，以及剩余动作 |
-| `status.md` | 自动生成的阅读入口，显示目标、进度、阻塞、下一步和文档链接 |
-| `.aimship/state.json` | 工具维护的状态，包含目标／阶段、文档引用、版本绑定及关联仓库／worktree／代码位置 |
+你明确通过后，批准会关联该文档版本，Agent 自动开始下一授权阶段，不再询问是否开始。如果你已明确安排换会话继续，Agent 会先保存交接信息，具体见[会话安排](#continue)。聊天中会显示当前阶段、待审文档、审核状态和下一阶段。文档批准与最终交付验收分开。
 
-SQL 标明目标、方言、版本／结构依据、执行条件，按顺序组织语句并关联需求和设计，在技术方案结束前准备完成。Markdown 中的 SQL 片段或迁移文件引用不能替代它。生成 SQL 不代表获准执行数据库操作或修改工程迁移机制。
+授权内的实施、Agent 评审、缺陷修复和复测可连续推进。实施按批次审核，全部完成后整体审核，再独立验证。新增实质决定和生产动作仍需对应授权。
 
-已有工程 HTTP 契约继续作为权威来源，避免维护另一份相互冲突的副本。项目当前版本和目标版本在 PRD／Scope 中记录，并注明工程来源和观察依据；未设置版本时如实说明。`plan.md` 记录实际改动，审核与测试结果定位准确的 commit、构建或未提交内容。多仓库分别记录版本和对象引用，与 Aimship 规则版本、状态格式及保存 revision 区分。交接记录最终代码对象和真实合并／发布状态，目标版本不代表已发布版本。
+<a id="results"></a>
+<a id="3-查看进度与成果"></a>
+## 4. 查看进度与成果
 
-### 固定大纲和可追溯编号
+从交付目录的 **`status.md`** 查看当前阶段、待审文档、审核状态、阻塞事项、下一阶段和成果入口。查看验证结论时，同时关注对应版本、环境和证据。缺少账号、工具或环境的检查会标为阻塞或未执行，不能计为通过。
 
-新文档遵循[统一模板和规则](../skills/aimship/references/document-patterns.md)，保留章节顺序和稳定锚点，可翻译展示标题。不适用章节说明原因，小需求使用相同大纲、缩短内容。未选择的阶段不生成空文档，也不按“小需求”随意合并文件。
+<a id="delivery-structure"></a>
+### 交付目录与文档
 
-| 编号 | 含义 |
-| --- | --- |
-| `REQ-001`、`AC-001` | 需求、验收标准 |
-| `B-001`、`TASK-001` | 实施批次、任务 |
-| `PAGE-001`、`Q-001` | 原型页面、待决问题 |
-| `TC-001`、`RUN-001` | 测试用例、实际验证执行 |
-| `REV-001`、`CHG-001` | 审核、重要变更 |
+默认每个需求在 `~/Aimship/` 下使用独立交付目录，代码保留在原仓库。
 
-各类编号从 `001` 开始，在包含已废弃条目的历史最大值后递增，三位是最小补零宽度。旧编号不用于另一项义务。同一命名空间和适用版本内，一个编号只有一处有效定义，其他文档引用该定义。分类或排版变化保留编号，拆分／合并则创建新编号并关联原编号。
+下方列出交付产物及其用途；实际生成范围由所选阶段和输入条件确定，未选阶段不生成空文档。`prd.md` 与 `scope.md` 是需求入口的两种选择，并非每个需求都要同时生成。
 
-需求／验收通过引用关联到设计、任务、代码对象、审核、用例版本和实际执行，允许多对多关联；不能因数字相同就认定 `REQ-001` 对应 `TC-001`。可独立测试的公共规则、权限和质量要求应具有独立身份。外部编号保留原样，并携带来源／版本命名空间；无原编号时建立指向原文位置的本地映射。用例含义改变后产生新版本，先前失败及当时的用例和代码版本仍可追溯。
+```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-另一个需求/           # 独立的资料与进度
+```
 
-例如，`REQ-001 → AC-002 → TC-004@1 → RUN-003` 表示明确的需求到结果关联。RUN 同时记录被测代码／构建及证据，仅存在用例编号不能证明已执行。
+正式文档直接放在需求目录下；`source/` 保留采用的原件，`.aimship/` 保存内部记录。软件安装目录为 `~/.aimship/`，与各需求目录内的 `.aimship/` 分别管理。
 
-工具检查结构、引用和基础覆盖；Agent 仍需判断正文和断言是否真正满足需求。元信息合法不等于内容正确。
+文档名称、大纲和编号遵循统一模板。需求与验收标准关联到实施任务、审核、带版本的测试用例及执行结果。[交付文档参考](reference.zh-CN.md)进一步说明每种文档的生成条件和具体内容。
 
 <a id="changes"></a>
 <a id="review-verify-and-change"></a>
-## 5. 结果查阅与变更处理
+<a id="4-推进中需求发生变化"></a>
+## 5. 推进中需求发生变化
 
-通过 `status.md` 查看交付概况，并访问相关文档。Review 说明对改动的审核，验证记录说明实际执行了哪些断言。每项结果应定位对象／版本、范围、执行者、环境和证据。缺账号、工具或环境的检查保留为阻塞或未执行，并注明下一步，不能计为通过。
+说明发生了什么变化、原因以及希望保留的内容。如果已修改正式文档，指出位置，让 Agent 核对修改的含义。
 
-重要变更记录一次决定，然后更新受影响的可编辑需求、设计、契约、SQL 和用例，复核受影响的结论。原始资料与历史结果保留，无关的已完成工作不重置，也不通过降低验收标准掩盖实现失败。
+Agent 会分析对范围、设计、实现和验证的影响，记录决定，更新受影响的工作安排和文档。需要你判断的取舍会提出，其他授权内工作继续，原始采用资料继续保留。
 
-变更可以通过指令提出，也可以修改正式文档后要求 Agent 核对并同步影响。`status.md` 是生成视图，手动修改不能改变目标或代表验收；重建前需保留手改内容。内部 JSON 和视图元信息由工具管理。
+已批准文档发生实质变更时，回到对应阶段重审，依赖它的工作等待审核解决后再继续；旧批准和结果保留为历史，不能用旧批准放行新版。重审通过后，按依赖顺序恢复。无关工作不重置，排版和错字修正不需全量重审。
+
+重要变化及影响记录在 `change-log.md`，后续安排从 `status.md` 查看。不要通过修改 `status.md` 来改变需求或表示验收；它是生成视图，已有手改内容需先保留，再由 Agent 核对和重建。
 
 <a id="continue"></a>
 <a id="continue-in-another-conversation"></a>
-## 6. 进度保存与会话接续
-
-在阶段或批次的稳定边界，请 Agent 保存进度并给出包含绝对交付路径的接续提示词。自行打开新会话，选择 Aimship：
+<a id="5-暂停后或换会话继续"></a>
+<a id="6-暂停后或换会话继续"></a>
+## 6. 会话安排与继续工作
 
-> 使用 Aimship 继续 `/绝对路径/Aimship/20261023-订单导出/` 中的交付。读取状态和当前文档，继续执行已记录的后续工作。
+### 维护者的分窗口实践
 
-切换宿主也使用同一个目录，并分别授权访问。新会话读取当前状态和必要输入，不要求复制完整聊天或重复所有测试。不会自动创建会话或进行云同步。
+为了控制上下文不断累积带来的负担，维护者实际使用过以下会话（窗口）安排：
 
-代码仓库搬迁后，提供新位置，核对仓库身份后修复引用。操作中断后，先检查真实产物与副作用再重试。revision 冲突需要协调，不能强制覆盖。读取、检查和接续会报告过期或手改视图；保留手改后通过明确的 render 重建。状态保存成功而视图生成失败时，只修复视图，不重放已经成功的状态写入。
+| 工作内容 | 窗口安排 |
+| --- | --- |
+| 需求／Scope | 一个窗口 |
+| 技术文档、SQL、接口文档 | 共用一个窗口 |
+| 测试用例设计 | 一个窗口 |
+| 实施计划 | 一个窗口 |
+| 实施 | 每个实施批次一个窗口，包含该批 Agent 评审 |
+| 整体 review | 一个窗口 |
+| 测试执行 | 每个测试批次一个窗口 |
 
-<a id="parallel"></a>
-<a id="work-on-two-requests-at-once"></a>
-## 7. 多需求并行管理
+这是使用经验，不是强制分窗规则或阶段完成条件。可按任务规模、资料量和上下文累积情况调整；合并后的效果需在实际工作中核对。技术文档、SQL 和接口共用窗口时，仍按既定顺序先审技术文档，再逐份审核适用的接口／SQL 文档，不能因为共用窗口而跳过审核。
 
-不同需求使用不同交付目录，例如 `~/Aimship/通知偏好/` 和 `~/Aimship/订单导出/`，每个交付只保留一个写入会话。代码可以关联不同仓库，也可以关联同一个仓库。
+实施批次与测试批次承担不同工作。测试批次按验证安排划分，不要求与实施批次一一对应，也不要求每个实施批次结束后立即测试。新窗口本身不保证判断独立或质量；每个新会话仍需读取相关的完整正式文档、已保存状态和实际成果，不能只靠简短聊天摘要接手。
 
-A 正在应用 checkout 中实施时，B 可以将其作为只读参考继续设计。B 也要写代码之前，安排串行实施或独立 checkout／worktree；已有隔离环境时优先复用。共享接口、数据库和测试资源也需要在计划中协调。分支完成不等于集成完成。
+### 安排新会话与交接
 
-关联或改变代码范围、改变工作目录、准备实施时，Agent 检查已知资料根目录中可访问的记录，包括较早但未结束的交付；已结束交付也可能留下待集成依赖。未知目录、不可访问或过期记录、Aimship 外的工作会限制检查范围。Aimship 不提供全局锁、自动 Agent 调度、自动创建 worktree 或自动合并。
+Aimship 负责阶段、产物、审核与交接规范，本身不创建新会话。需要换窗口时，由你在所用的 AI 工具中开启新会话，再提供同一交付目录和交接信息。
 
-<a id="update"></a>
-<a id="update-or-stop-using-aimship"></a>
-## 8. 软件升级与交付兼容
+如果希望文档通过后换窗口，在批准时一并说明，例如：“这份文档通过。先保存交接信息，我会在新窗口继续。”Agent 会记录批准和你的续接安排，不在当前会话直接开始下一阶段。实施或测试批次则可以说：“完成本批，保存结果和交接信息，下一批在新会话继续。”这不增加对执行记录的人工审批要求。
 
-升级到已发布的预览通道版本：
+结束当前会话前，请 Agent 保存进度、审核状态、未解决问题和下一步，并给出交付目录的完整路径及相关代码位置。新会话中选择 Aimship，提供同一个交付目录；Agent 读取相关的完整正式文档和状态、核对实际成果后，按已保存的安排继续。更换 AI 工具时也要确保能访问同一份资料和代码。
 
-```sh
-npx aimship@preview install
-```
+同一交付只保留一个写入会话，旧会话停止写入后再由新会话接手。待审文档仍需你明确通过，换窗口不能跳过审核。进度和下一步仍从同一份 `status.md` 查看，无需复制完整聊天。
 
-源码／本地候选版本则使用该版本的安装器，指向相同安装目录。已有宿主登记、配置、自定义内容和交付资料都会保留。未修改的管理文件可重复安装，安装器报告旧／新版本及冲突。没有后台自动升级或常驻进程。
+### 处理中断与版本变化
 
-**软件升级使用 `install`。** 底层 `update` 命令修改交付状态，不是软件升级。日常使用绑定的本地稳定入口和规则，无需反复下载 npm 包。
+意外中断时，让 Agent 先核对已经完成的操作，避免重复写入或重跑有副作用的动作。代码仓库搬迁后提供新位置，由 Agent 核对身份后更新关联。状态冲突或进度视图异常需要先协调或修复，不能强行覆盖。
 
-安装升级后，正在运行的会话仍可能保留旧规则。先保存现状，再在稳定边界采用当前核心和阶段规则；无法可靠刷新上下文时开启新会话。版本不一致需先协调，才能继续写入流程状态。
+软件升级后，旧会话可能保留旧规则。先保存工作，再让 Agent 在稳定边界核对当前版本与交付记录；无法可靠刷新时开启新会话。旧格式交付需要明确迁移、采用规则并整理相关文档后继续，未知格式保持只读。已有原件和历史结果保留，不补造过去未执行的工作，也不将旧完成记录当作批准；恢复协议供 Agent 查阅 [CLI 文档](cli.md)。
 
-schema 1 的旧交付，需要显式迁移选中的交付、采用新规则、整理文档后，再继续阶段推进。迁移保留原件和历史结果，不补造过去缺失的计划，也不会自动重写全部正文。未知格式保持只读，软件升级不会扫描改写所有已结束交付。供 Agent／贡献者使用的 [CLI 协议](cli.md)说明具体恢复方式。
+<a id="parallel"></a>
+<a id="work-on-two-requests-at-once"></a>
+<a id="6-同时推进多个需求"></a>
+## 7. 同时推进多个需求
 
-<a id="uninstall"></a>
-## 9. 宿主断开与卸载
+不同需求使用独立交付目录，每个交付只保留一个写入会话。向 Agent 说明已知的共享代码、接口、数据库或测试环境。
 
-只断开一个宿主，保留核心和其他宿主登记：
+一个需求正在修改代码时，另一个可以先做只读分析。两个需求都要修改同一份代码之前，安排串行实施或独立 checkout／worktree，并优先复用已有隔离。Agent 会根据可访问的已知交付记录核对重叠范围，在计划中记录协调方式；未知或过期记录、Aimship 外的工作不在完整掌握范围内。
 
-```sh
-node "$HOME/.aimship/bin/aimship.mjs" uninstall --host cursor
-```
+各需求分别查看自己的进度和结果。分支完成不代表集成完成；Aimship 不提供全局锁、自动 Agent 调度、自动创建 worktree 或自动合并。
 
-其他已登记宿主还需要的共享入口会保留。断开最后一个宿主也保留核心，以便诊断或重新连接；兼容宿主仍可能发现剩余的共享入口。
+<a id="completion"></a>
+<a id="decide-when-work-is-done"></a>
+<a id="7-完成交付"></a>
+## 8. 完成交付
 
-移除所有受管理的软件和宿主入口：
+查看交接记录中的成果位置、使用方式、审核和验证结论、遗留问题与后续事项，并对照原目标判断是否接受。
 
-```sh
-node "$HOME/.aimship/bin/aimship.mjs" uninstall
-```
+Agent 会分别记录目标完成、用户验收、合并和部署的实际情况。要求预览不代表缩短目标；明确提前结束时，交接中保留原目标和未完成工作。
 
-完整卸载保留交付资料、用户代码、自定义文件和必要配置。修改过或不属于它管理的文件会保留并报告。完全移除后，稳定入口也会移除；重启宿主会话以清除缓存规则。删除交付历史是另一项需要明确提出的操作。
+后续小修正可以继续原交付，并保留此前完成记录；新目标或大幅重新设计则建立关联的新交付。
 
 <a id="troubleshoot"></a>
-## 10. 常见问题
+<a id="8-使用中遇到问题"></a>
+## 9. 使用中遇到问题
 
-| 现象 | 处理方式 |
+| 情况 | 如何处理 |
 | --- | --- |
-| 找不到 Aimship，或出现重复项 | 刷新宿主，检查实际选择器及返回的入口路径／版本。不要删除无关入口；安装健康不代表宿主已经发现 Skill。 |
-| 目录访问被拒绝 | 在该宿主授权需要的资料／代码根目录，报告具体操作，不搬动资料或关闭权限控制来绕过限制。 |
-| 管理位置被修改或被其他文件占用 | 保留内容，检查归属，明确合并定制内容后再重试。 |
-| 安装只完成了一部分 | 查看 `status`，排除报告的原因，在同一目录重跑完全相同的待恢复版本；不要在恢复途中换版本。 |
-| 稳定入口缺失或损坏 | 在对应版本的源码／包安装器中执行 `node bin/aimship.mjs status --home <安装用户目录>`；该操作只诊断，检查原因后再运行安装器修复。 |
-| 版本与预期不一致 | 查询稳定安装入口；源码或旧版本 CLI 可能报告不同版本，继续前刷新当前绑定。 |
-| 包／版本不存在或认证失败 | 核对包名、明确版本和 registry。下载失败不算安装完成，不在问题报告中粘贴凭据。 |
-| `status.md` 过期或被手改 | 请 Agent 读取当前状态和正文，保留手改内容后明确重建视图，不用视图覆盖状态。 |
-| 正式文档在流程外被修改 | 核对含义与受影响工作；状态和视图 revision 相同，也不证明正文未变。 |
-| 旧交付无法继续 | 请 Agent 分别检查迁移、规则采用和文档整理，保留历史结果并报告未解决的阻塞。 |
-
-反馈问题时附上 Aimship 版本、宿主／版本、具体命令或操作、预期与实际结果，以及最小合成复现。隐去凭据、个人路径和私有资料，通过 [GitHub Issues](https://github.com/clsx/aimship/issues)提交。参与开发请看 [CONTRIBUTING](../CONTRIBUTING.md)。
+| 无法访问资料或代码 | 在当前 AI 工具授权需要的目录，说明失败的具体操作，不通过搬动资料绕过权限限制 |
+| 进度页与实际成果不一致 | 请 Agent 核对当前记录和实际文件，保留手改内容后重建进度页 |
+| 正式文档在会话外被修改 | 指出修改位置，请 Agent 核对含义及对后续工作的影响 |
+| 旧交付无法继续 | 请 Agent 检查格式迁移、规则采用和文档整理，保留历史结果并说明阻塞原因 |
+| 找不到 Aimship、安装或版本异常 | 查看 README 的[安装与升级问题](../README.zh-CN.md#installation-troubleshooting) |
 
-<a id="completion"></a>
-<a id="decide-when-work-is-done"></a>
-## 11. 交付完成条件
+反馈问题时提供 AI 工具和 Aimship 版本、具体操作、预期与实际结果，以及可复现的最小资料；隐去凭据、个人路径和业务数据，通过 [GitHub Issues](https://github.com/clsx/aimship/issues)提交。
 
-以本次委托的终点为准：设计委托完成约定方案即可，开发委托包含必要的审核和验证。要求预览当前结果不代表缩短目标。明确提前结束时，在交接中保留原目标和未完成工作。
+## 相关参考
 
-目标完成、用户验收、合并和部署分别记录。后续小修正可重开原交付并保留此前关闭记录；新目标或大幅重新设计则建立关联的新交付。父子交付管理和多 Agent 编排暂不自动化。
+<a id="artifacts"></a>
+<a id="keep-only-useful-artifacts"></a>
+文档生成条件、阶段产物、大纲与编号规则见[交付文档参考](reference.zh-CN.md)。这些规则由 Agent 随工作维护，无需在开始前逐项掌握。
+
+<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)。

package/docs/installation.md

@@ -1,24 +1,28 @@
 # Installation guide moved
 
-Installation and lifecycle instructions now live in the complete user guide. This page preserves the old entry point.
+Installation and software lifecycle commands live in the README. The Guide covers using Aimship after installation. This page preserves the old entry points.
 
-- [English guide](guide.md#install)
-- [中文使用指南](guide.zh-CN.md#install)
+- [English installation instructions](../README.md#install)
+- [中文安装说明](../README.zh-CN.md#install)
 
 <a id="installation-layout"></a>
+<a id="registry-installation-after-publication"></a>
+Installation options: [English](../README.md#install) · [中文](../README.zh-CN.md#install). Delivery layout: [English](guide.md#delivery-structure) · [中文](guide.zh-CN.md#delivery-structure).
+
 <a id="source-and-local-packages"></a>
+Local package installation: [English](../README.md#install) · [中文](../README.zh-CN.md#install). Source packaging: [Contributing](../CONTRIBUTING.md#isolated-installation-check).
+
 <a id="isolated-trial"></a>
-<a id="registry-installation-after-publication"></a>
-Installation layout, source/local packages and isolated trials: [English](guide.md#install) · [中文](guide.zh-CN.md#install).
+Isolated installation validation: [Contributing](../CONTRIBUTING.md#isolated-installation-check).
 
 <a id="host-entry-and-reload"></a>
 Host entry and reload: [English](guide.md#hosts) · [中文](guide.zh-CN.md#hosts).
 
 <a id="add-a-host-inspect-and-update"></a>
-Add a host and inspect the installation: [English](guide.md#hosts) · [中文](guide.zh-CN.md#hosts). Update software: [English](guide.md#update) · [中文](guide.zh-CN.md#update).
+Upgrade, add a host or inspect the installation: [English](../README.md#update) · [中文](../README.zh-CN.md#update).
 
 <a id="disconnect-or-uninstall"></a>
-Disconnect or uninstall: [English](guide.md#uninstall) · [中文](guide.zh-CN.md#uninstall).
+Disconnect or uninstall: [English](../README.md#uninstall) · [中文](../README.zh-CN.md#uninstall).
 
 <a id="troubleshooting-and-recovery"></a>
-Troubleshooting and recovery: [English](guide.md#troubleshoot) · [中文](guide.zh-CN.md#troubleshoot).
+Installation problems: [English](../README.md#installation-troubleshooting) · [中文](../README.zh-CN.md#installation-troubleshooting). Delivery continuation: [English](guide.md#continue) · [中文](guide.zh-CN.md#continue).

package/docs/reference.md

@@ -0,0 +1,78 @@
+# Aimship Delivery Document Reference
+
+[中文](reference.zh-CN.md) · [Guide](guide.md) · [README](../README.md)
+
+Use this reference to look up document generation conditions, stage outputs and identifier rules. Start with the Guide for everyday use.
+
+Use the [annotated directory tree in the Guide](guide.md#delivery-structure) as the layout reference. Formal documents are directly in the request directory, new prototypes in `prototype/`, preserved inputs in `source/`, and machine records/evidence in `.aimship/`. There is no extra `docs/` or `sql/` layer within a delivery.
+
+## Choose the requirement authority
+
+| Input condition | Requirement document | Prototype handling |
+| --- | --- | --- |
+| An authoritative PRD/prototype is supplied for adoption | `scope.md` records adopted versions, scope, gaps, decisions and acceptance; originals remain unchanged | Reuse covered interactions; create a prototype for uncovered interaction changes within the commissioned endpoint |
+| An idea, discussion, screenshots or scattered references | Author `prd.md`, including scope and acceptance | Create a prototype when the commissioned work changes interactions and existing material does not cover them |
+| Technical refactoring or a known-cause fix | Author `prd.md` describing the technical goal, boundaries, behavior constraints and acceptance | No prototype when there is no interaction change |
+| Independent investigation, review-only or verification-only | PRD/Scope defines that commission and its endpoint | Do not invent a future implementation or prototype |
+
+`prd.md` and `scope.md` are alternatives for the requirement authority, not duplicate descriptions to create together. If you explicitly commission maintenance of an existing editable authoritative PRD and it fully expresses this delivery's scope, authorization and endpoint, register and reuse it. Earlier authorship alone does not make adopted material editable.
+
+Preserve incoming versions in `source/`, including externally supplied PRDs, prototypes and images. Generated formal documents stay in the locations above. External originals are not rewritten when requirements change. A URL alone may not preserve a version; the agent records the available source/version and any access gaps. Reading text, inspecting a visual, interacting with a prototype and editing its original format are distinct capabilities.
+
+## Stage outputs and content
+
+Stage names are stable identifiers. This table is a catalog, not a fixed sequence; the accepted arrangement selects stages and dependencies. Every delivery retains the original request, a requirement/scope authority and state records, even when no separate requirements stage is needed. Sharing `plan.md` or `testing.md` does not complete both stages automatically: each stage retains its own status and result. Documents are drafted when their stage begins, and file creation alone does not establish completion.
+
+| Stage | When used | Output and content |
+| --- | --- | --- |
+| `frame` | The problem or intended result needs clarification | Goal/background section of PRD/Scope: problem, outcome, non-goals and assumptions |
+| `requirements` | Requirements need authoring or adoption | `prd.md`: goals, scope, requirements, states, acceptance and arrangement; or `scope.md`: source adoption, scope, exclusions, decisions, acceptance and arrangement |
+| `scope` | Commission boundaries need explicit resolution | Update PRD scope or Scope goals/boundaries; no second requirements document |
+| `prototype` | Required interaction changes are not covered by existing material | New HTML at `prototype/index.html` with related assets; other agreed formats or reused entries are registered |
+| `diagnose` | An independent investigation is explicitly arranged | `diagnosis.md`: goal, symptoms, environment, evidence, causes, unknowns and conclusion |
+| `tech-design` | Technical solution needs designing | `tech-design.md`: basis, architecture, modules, data/contracts, errors, risks and requirement coverage; SQL is produced and reviewed in contract after this design is approved |
+| `contract` | Interfaces or database changes need formal artifacts | HTTP: `openapi.yaml` or the registered authority; agreed non-HTTP format; independent SQL per target, reviewed individually |
+| `test-design` | Test cases need authoring | `testing.md`: basis, environment, cases/assertions and requirement/acceptance coverage |
+| `plan` | Before any implementation, including one small batch | `plan.md`: basis, batches, tasks, validation approach, execution section and remaining work |
+| `implement` | Execute the accepted plan | Code in its repositories; actual task status, objects and deviations in the same `plan.md` |
+| `review` | Review a batch, the integrated result or a review-only commission | `review.md`: review basis, each review's scope/findings/resolution and conclusion |
+| `verify` | Execute versioned cases after the required review, or a verification-only commission | Append execution batches/RUNs, actual results/evidence, retests and conclusion to the same `testing.md` |
+| `handoff` | Deliver the agreed endpoint | `handoff.md`: goal, artifacts, usage, review/verification results, limits and completion/acceptance/integration outcomes |
+
+During development, test-design precedes plan; each document follows the [review flow](guide.md#review-documents-and-continue). `plan` completes before the first implementation. Each implementation batch is reviewed, followed by overall review and independent verification. Test code can be authored during implementation; there is no full testing gate imposed after each batch. For one batch, one review may cover both batch and overall scope if explicitly recorded. Verification-only work may adopt existing versioned cases without claiming to have executed `test-design`.
+
+Ordinary debugging and known-cause bugs do not add `diagnose`. Fix implementation defects in implementation, design errors in technical design, requirement gaps in PRD/Scope, and incorrect expectations in versioned cases. A major unknown requiring separate investigation needs a recorded stage adjustment; dependent work waits.
+
+## SQL, changes and progress
+
+| Artifact | Generation rule and content |
+| --- | --- |
+| `database.sql` | Required when database structures or data change; one database target uses this single root-level file |
+| `database-<id>.sql` | Multiple independent database targets get one file each; use a stable target ID |
+| `change-log.md` | Record meaningful changes: reason, old/new meaning, decision, affected documents/work and remaining actions |
+| `status.md` | Generated reading entry: goal, progress, blockers, next action and document links |
+| `.aimship/state.json` | Managed state: goal/stages, document references, version binding and associated repositories/worktrees/code locations |
+
+SQL identifies the target, dialect, version/schema basis and execution conditions, and links ordered statements to requirements/design. It is prepared and individually reviewed in contract after technical design approval and before test cases. A Markdown SQL snippet or migration reference does not replace this deliverable. Generating SQL does not authorize executing it or changing a repository's migration mechanism.
+
+Existing engineering HTTP contracts remain authoritative; avoid a second competing copy. Project current and target versions are recorded in PRD/Scope with their engineering source and observation basis; an unspecified version remains unspecified. `plan.md` records actual changes, while review and test results identify the exact commit/build or uncommitted content. Each repository has its own version and object references. These differ from Aimship’s rules version, state schema and save revision. The handoff records final code objects and actual merge/release status; a target version does not establish publication.
+
+## Fixed outlines and traceable identifiers
+
+New documents follow [shared templates and rules](../skills/aimship/references/document-patterns.md). Section order and stable anchors are retained; visible headings can be translated. Inapplicable sections explain why. Short tasks use the same outline, with shorter content. Unselected stages do not produce empty documents, and there is no arbitrary small-task merging.
+
+| Identifier | Meaning |
+| --- | --- |
+| `REQ-001`, `AC-001` | Requirement and acceptance criterion |
+| `B-001`, `TASK-001` | Implementation batch and task |
+| `PAGE-001`, `Q-001` | Prototype page and tracked question |
+| `TC-001`, `RUN-001` | Test case and actual verification run |
+| `REV-001`, `CHG-001` | Review and meaningful change |
+
+Each series starts at `001` and advances beyond its historical maximum, including retired items; three digits are the minimum width. An ID is never reused for a different obligation. Within a namespace and version, an identity has one effective definition; other documents reference it. Classification or layout changes retain the ID, while splits/merges create new IDs linked to the originals.
+
+References connect requirements/acceptance to design, tasks, code objects, reviews, case versions and actual runs. These relationships may be many-to-many: `REQ-001` and `TC-001` are not related merely because their numbers match. Shared rules, permissions and quality requirements receive independent identities when independently testable. External IDs retain their spelling and source/version namespace; sources without IDs receive local mappings to their original locations. Changed case meaning gets a new version; earlier failures and their case/code versions remain traceable.
+
+For example: `REQ-001 → AC-002 → TC-004@1 → RUN-003` records the explicit requirement-to-result relationship. A RUN also identifies the tested code/build and evidence; the case ID alone does not prove execution.
+
+The tools check structure, references and basic coverage. The agent must still assess whether the content and assertions actually satisfy the requirement; valid metadata alone is not proof.