aimship 0.1.0-preview.7 → 0.1.0-preview.9

package/docs/guide.zh-CN.md

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

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).