chreode-ship 0.8.2__tar.gz

chreode_ship-0.8.2/.gitignore

@@ -0,0 +1,12 @@
+.DS_Store
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.venv/
+__pycache__/
+*.py[cod]
+/build/
+dist/
+*.egg-info/
+.ship/cache/
+.worktrees/

chreode_ship-0.8.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ship contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

chreode_ship-0.8.2/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.5
+Name: chreode-ship
+Version: 0.8.2
+Summary: Independent project setup for Ship skills, CI feedback, and Codex Review Gate
+Project-URL: Source, https://github.com/Chreode/ship
+Project-URL: Issues, https://github.com/Chreode/ship/issues
+Project-URL: Documentation, https://github.com/Chreode/ship/blob/main/docs/install.md
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: tomlkit<1,>=0.13
+Description-Content-Type: text/markdown
+
+# Ship 安装
+
+Ship 的项目安装包名为 `chreode-ship`，主安装渠道是 PyPI，使用 `uvx` 运行一次性项目安装器。
+[GitHub Releases](https://github.com/Chreode/ship/releases) 保存版本说明及同批 wheel、sdist 和 `SHA256SUMS`，
+用于校验、归档和备用安装；用户安装无需注册 PyPI 账号。
+本文使用 `@latest` 请求最新发布的安装器；需要复现指定版本时，将 `latest` 换成目标版本号。
+可用版本见 [PyPI 项目页](https://pypi.org/project/chreode-ship/)，未发布的源码可用文末的本地构建验证。
+
+## 安装
+
+需要已有的 [uv](https://docs.astral.sh/uv/getting-started/installation/)。运行时需要 Python 3.11+，uv 可按需自动获取；
+不允许自动下载时在 `uvx` 后加 `--no-python-downloads`，并预先准备兼容 Python。
+在要使用 Ship 的项目根目录运行；也可用 `--project /绝对路径` 指定目标。Git 项目须指向仓库或 worktree 根目录。
+命令会下载包及依赖、使用 uv 缓存，并立即写入所选组件的项目文件；不另弹确认。
+
+```bash
+uvx chreode-ship@latest install ship
+```
+
+Codex 是默认宿主；Claude Code 用户追加 `--host claude`。安装后在目标项目新开任务，核对实际加载的技能路径。
+
+三个组件独立安装：
+
+| 组件 | 内容 |
+| --- | --- |
+| `ship` | 五种职责 Skill、CI 反馈 Skill、Python waiter、共享合同及宿主角色配置 |
+| `ship-feedback` | 生成汇总当前 PR 检查的 workflow，向 Writer 返回 CI 失败或通过结果 |
+| `codex-review-gate` | 生成独立的 Codex Review Gate workflow，只检查 Codex 审查反馈 |
+
+需要 GitHub CI 反馈时，在同一项目追加：
+
+```bash
+uvx chreode-ship@latest install ship-feedback
+```
+
+将生成的 `.github/workflows/ship-feedback.yml` 提交并合入默认分支后才会生效。它使用 GitHub Actions 自带的
+`GITHUB_TOKEN`，无需新 App 或 Secret；已出现的测试失败会先返回，即使 Codex 未触发或仍在等待。
+反馈不解析 Codex 评论、不请求模型，不应设为 required check；反馈通过后仍需满足项目的原生合并保护。
+
+需要独立 Codex Gate 时，运行：
+
+```bash
+uvx chreode-ship@latest install codex-review-gate
+```
+
+它只生成接入文件，并输出与已安装 Action 完整 SHA 对应的 Gate 采用说明 URL。仓库管理员按该固定版本说明
+配置 App、凭据和合并规则，再提交 workflow；安装器不会执行这些平台操作，也不会发起 `@codex review`。
+`install gate` 是兼容别名；`install all` 是三项并集，三个组件也可按任意顺序分别安装。
+
+## 写入范围与模型配置
+
+| 项目内路径 | 写入内容 |
+| --- | --- |
+| `.ship/` | 许可证、安装记录；选择 `ship` 时还包括合同、角色默认配置和 waiter |
+| `.agents/skills/ship-*/` | Codex 的六份 Skill |
+| `.codex/agents/{writer,researcher,verifier,reviewer}.toml` | Codex 四个子角色配置 |
+| `.codex/config.toml` | 需要时把 `agents.max_depth` 补为至少 `2`，保留其他配置 |
+| `.claude/skills/ship-*/` | Claude Code 的六份 Skill，替代 Codex 专用资源 |
+| `.github/workflows/ship-feedback.yml` | 仅选择 `ship-feedback` 或 `all` 时生成 |
+| `.github/workflows/codex-check.yml` | 仅选择 `codex-review-gate` 或 `all` 时生成 |
+
+Git 项目通过实际 `info/exclude` 精确忽略安装器拥有的本地资源；不忽略整个 `.agents/` 或 `.codex/`，
+不改 `.gitignore`，不 untrack 既有文件，两种 workflow 保持可提交。worktree 可能共用主仓的 Git exclude。
+安装器不创建或修改项目的 `AGENTS.md`、`CLAUDE.md`、`CODEOWNERS`，遇到同名资源或受管理配置冲突时停止。
+
+直接编辑项目 `.codex/agents/对应角色.toml` 的 `model` 和 `model_reasoning_effort`：
+
+| 角色 | 默认模型 | 默认 effort |
+| --- | --- | --- |
+| Writer | `gpt-5.6-sol` | `medium` |
+| Reviewer | `gpt-5.6-sol` | `high` |
+| Researcher、Verifier | `gpt-5.6-terra` | `medium` |
+
+同版本重复安装保留这两个字段，其余字段由安装器管理；卸载会移除角色配置及其中的模型设置。
+单次任务选择优先，配置的模型须由宿主支持。Commander 沿用顶层任务的设置；其他宿主使用其原生模型配置。
+具体选择规则见安装后的 `.agents/skills/ship-commander/SKILL.md`；Claude Code 宿主读取对应的
+`.claude/skills/ship-commander/SKILL.md`。
+
+项目安装器不操作全局 Plugin，也不改用户级 Skill、项目信任、沙箱或账号权限。若以前通过宿主插件管理
+安装过 Ship，那份历史安装的升级和卸载仍由宿主管理；先确认其来源和版本，避免重复加载。
+uv 的项目外缓存可用 `uv cache dir` 查看，项目卸载不会清除它。
+
+## 查看、卸载与升级
+
+在已安装 Ship 的项目目录运行：
+
+```bash
+uvx chreode-ship@latest files
+uvx chreode-ship@latest uninstall
+```
+
+`files` 查看已安装清单；`uninstall` 先检查冲突，再恢复原有配置并移除自己的文件和 Git 忽略区块。
+它不会撤销远端 workflow、App、Environment 或 Ruleset。安装记录位于 `.ship/install.toml`；
+兼容的旧安装记录可以由新安装器处理。若安装器报告状态版本或 schema 不受支持，不要手改 receipt；使用
+该记录对应的原发行名、版本和可信 wheel 执行 `files`、`uninstall`，再安装目标版本。
+内部 Python 模块仍叫 `keel_ship`，它不是用户安装时输入的包名。
+
+尚未发布时，可在 Ship 源码目录构建本地 wheel，再指定另一个目标项目验证：
+
+```bash
+uv build --wheel
+```
+
+从 `dist/` 选择本次构建生成的 wheel，将下列占位路径替换为该文件的完整路径：
+
+```bash
+uvx --isolated --no-python-downloads --from '/abs/path/to/chreode_ship-<version>-py3-none-any.whl' chreode-ship install ship --project /abs/project
+```
+
+GitHub Release 附件也可作备用来源：从目标版本的 Release 页面下载 wheel 并核对 `SHA256SUMS`，
+再将该文件路径传给上述 `--from`。Release 说明中的安装命令会固定到该次发布版本。
+这是同一个项目安装器，不是另一套宿主安装方式。
+
+完全离线安装还需提前准备 uv、兼容 Python、wheel 及其依赖；只下载 Ship wheel 并不等于依赖已齐备。

chreode_ship-0.8.2/README.md

@@ -0,0 +1,380 @@
+# Ship
+
+让 **Codex 和 Claude Code** 按需分工、处理反馈，把交给它的活做完。
+可选的 **Gate** 把 GitHub 上的 Codex 审查结果接到合并规则：这一版代码通过审查，才满足这道合并条件。
+
+[安装](#安装) · [第一次使用](#第一次使用) · [为什么用 Ship](#为什么用-ship) · [怎样工作](#它怎样工作) · [怎样用好](#怎样用好-ship) · [代价与局限](#代价与局限) · [文档与维护](#后续入口)
+
+## 安装
+
+公开安装包名为 `chreode-ship`，主渠道是 [PyPI](https://pypi.org/project/chreode-ship/)。
+在要使用 Ship 的项目根目录运行，使用 PyPI 上最新发布的安装器：
+
+```bash
+uvx chreode-ship@latest install ship
+```
+
+需要先安装 [uv](https://docs.astral.sh/uv/getting-started/installation/)。uv 可以按包要求获取合适的
+Python；若你禁止自动下载 Python，确认本机已有 Python 3.11+，并在 `uvx` 后加
+`--no-python-downloads`。Codex 是默认宿主；Claude Code 明确运行：
+
+```bash
+uvx chreode-ship@latest install ship --host claude
+```
+
+命令会下载包及依赖、使用 uv 缓存，并立即写入项目技能、角色配置和安装记录，不另弹确认。
+同一发布流程在 [GitHub Releases](https://github.com/Chreode/ship/releases) 记录版本，并归档同批 wheel、
+源码包与校验文件；日常安装仍以 PyPI 命令为入口。
+
+| 组件 | 安装内容 |
+| --- | --- |
+| `ship` | 角色与反馈技能、可编辑的角色默认模型、Python waiter |
+| `ship-feedback` | 独立的 CI 汇总 workflow，向 Writer 返回失败或通过结果 |
+| `codex-review-gate` | 独立的 Codex 审查检查 workflow，需另行配置 GitHub App 和合并规则 |
+| `all` | 三项组件的并集 |
+
+安装器通过 Git `info/exclude` 精确忽略项目本地资源，workflow 保持可提交；不修改项目的 `AGENTS.md`、
+`CLAUDE.md` 或 `CODEOWNERS`，不安装全局 Plugin，不提供 marketplace 入口。
+本版本完整写入范围、组件接入、模型配置及卸载方式以 [安装说明](docs/install.md) 为准。
+
+## 第一次使用
+
+安装角色后，在目标项目**新开一个任务**，先确认 Agent 实际发现了哪一份 Ship、来自哪个路径。
+已有任务不一定重新加载新文件，也不要用“目录里有文件”代替加载确认。
+
+可以先给它一个没有写入动作的小任务：
+
+```text
+先只读查看这个项目，告诉我启动入口、已有的验证方式，以及你据此查看的文件位置。
+没有验证过的内容直接说不确定。现在不修改文件、不安装依赖、不创建 PR。
+```
+
+你应该拿到一份能对照文件检查的回答。这个任务可以由当前 Agent 完成，也可以在确有帮助时交给研究者；
+无需让五个角色轮流出场。确认它的工作方式适合你，再交付一个能亲手验收的小改动。
+
+## 为什么用 Ship
+
+用 AI 做项目，很容易遇到这样一个下午：你想给页面加个搜索框，Agent 很快把功能做出来了。打开改动一看，
+它还换了数据访问方式，抽出了一个通用搜索层，为“以后可能用到”加了几项配置。测试通过了，说明也写得
+很完整。接下来，你得弄清楚这些东西哪些值得留下。
+
+生成代码的速度上来了，理解和维护代码的时间却没有跟着变多。一个人做项目，研究方案、做决定、检查
+结果、处理返工，最后都要落到自己头上。哪怕把这些事交给几个 Agent，交接不清楚时，你仍然是那个
+到处补充背景、转述审查意见、催它继续的人。
+
+Ship 给 Agent 一套按需使用的分工方法。研究者查清问题，实现者完成改动并接着处理反馈，审查者根据
+原始需求重新判断。这几个职责可以拆开，也可以由当前 Agent 直接完成。
+
+它主要想替你省掉三件事：
+
+- **反复转述背景。** 研究者带回相关证据和结论，实现者不必重读整段搜索过程，你也不用替它找聊天记录。
+- **把问题转来转去。** 测试失败或审查发现 bug，原来的实现者继续修；需要你决定的才交回来。
+- **猜测“完成”是什么意思。** 交付要说明改了什么、实际验证了什么、哪里还没验证，让你有东西可以检查。
+
+例如搜索只涉及一个已有列表，当前 Agent 直接改就好；如果还不清楚数据分页和权限，先查清楚再写；
+如果几处逻辑容易相互影响，再请独立审查者看一遍。多一次交接应该换回具体帮助。
+
+Codex 和 Claude Code 本来就有工具和子代理能力，Ship 补充的是这些工作约定，无需另开一套 Agent 服务。
+如果你自己的项目规则已经做得很好，继续沿用就可以。是否值得用，要看它有没有减少你的追问和返工。
+
+## 它怎样工作
+
+### 子代理怎样协作
+
+还是用搜索功能举例。研究者先回答“拿到的是全量数据还是一页？权限在哪里限制？”，实现者据此修改，
+审查者再拿原始需求和这版代码检查“会不会只搜了第一页？是否为了拿全量数据绕过权限？”。
+
+Ship 默认给新子任务独立的聊天上下文。尤其审查时，不把实现者关于“为什么这样改已经够好”的长篇论证
+一起灌进去，让审查者有机会重新判断。实现者自己的上下文则保留，方便接着修复。
+
+#### 五种职责，按任务组合
+
+| 职责 | 交给它什么 | 应当拿回什么 |
+| --- | --- | --- |
+| Researcher · 研究 | 一个需要查清的事实问题 | 证据、结论，以及仍然不确定的部分 |
+| Writer · 实现 | 范围和完成标准明确的改动 | 可查看的产物、必要测试与验证，范围内问题的修复 |
+| Verifier · 验证 | 确定的一版改动和指定场景 | 实际通过、失败或未验证的结果 |
+| Reviewer · 审查 | 原始目标、限制和确定的一版改动 | 有证据的缺陷，或在所查范围内未发现问题 |
+| Commander · 统筹 | 有多个环节、依赖或分工的任务 | 分工与取舍、争议处理，以及到约定终点的推进 |
+
+“研究”“实现”“验证”“审查”也可以单独提出。你说“帮我查清楚这个接口”“修复这个问题”“看看这份
+改动有没有漏掉什么”就可以，Agent 根据职责选择 Skill。查一个问题没有必要先组队；修一个明显的错误，
+也没有必要让五个角色轮流发言。
+
+Skill 是 Agent 可以按任务读取的工作说明。宿主先让它看到技能名称和适用描述，Agent 判断是否需要读取
+正文，再按需要打开其中的参考材料。因此，Ship 不要求每个任务从头读完所有角色和合同。对日常问答、
+路径清楚的小修，完整交付流程可能只会添麻烦。
+
+Codex 的四份角色配置提供可编辑默认值：Writer 使用 `gpt-5.6-sol` / `medium`，Reviewer 使用
+`gpt-5.6-sol` / `high`，Researcher 与 Verifier 使用 `gpt-5.6-terra` / `medium`。创建者仍可在宿主允许的
+范围内按任务单次选择；需要覆盖已注册角色的默认值时使用 Commander 文档说明的通用 `default` 入口。
+研究不总是容易，审查也不总是需要最昂贵的配置。
+
+独立上下文并不能消除共同盲点。同一个模型可能在两次调用中犯同样的错，不同模型也可能一起相信错误的
+需求。它也不提供文件权限隔离：几个子代理若共享目录，仍可能影响同一批文件。并行写入要准备独立工作
+目录，访问权限要由宿主控制。具体接入方式见[角色使用说明](docs/usage.md#角色单用)。
+
+### Gate 是什么？看一个 PR 就明白
+
+假设你让 Agent 修好一个搜索功能，它提交了 PR，也就是一组等待合并的改动。你已经试过页面，
+但没有时间逐行看完它写的代码。接下来的工作可以这样做：
+
+1. **你或获授权的 Agent 在 PR 留下 `@codex review`。** Codex 再检查一遍代码。
+2. **Codex 找到问题，实现者继续修。** 例如搜索只查了第一页，第二页的书签一直找不到。
+3. **修好、推送新提交，再审查这一版。** Gate 核对 Codex 的结果确实对应当前提交；确认 clean
+   （审查未发现问题）后，把名为 `codex` 的检查变绿。
+4. **GitHub 检查其余合并条件。** 测试、必需审批等也都满足后，PR 才能合并；如果你另外启用了
+   GitHub 原生自动合并，它会在条件满足后完成合并。
+
+**Gate 就是把“Codex 看过了，而且这一版通过审查”变成 GitHub 会执行的合并条件。**
+这样你不用每次翻评论、对版本，再手工确认一遍审查状态。
+
+如果你见过 GitHub Copilot 的自动审查和批准，可以从相似的需求理解它：让 AI 参与合并前的检查。
+但配置时要分清：Copilot approvals 可以计入批准人数；**Ship Gate 提供的是必需检查，不增加一个
+Approve**。仓库如果还要求一位真人批准，这个人仍然要来。
+[Copilot 官方说明](https://docs.github.com/en/copilot/concepts/agents/code-review#copilot-approvals)
+解释了它的批准机制。
+
+### 为什么选 Codex review
+
+一个人开发时，AI 写代码常常比自己读代码快。我们需要一位能持续参与的审查者，也已经在使用 Codex。
+复用已有的 Codex review，就不必仅为了这一步再引入一套 Copilot 的订阅或组织计费安排。
+Copilot 是否增加开销取决于你已有的权益；Codex 的审查也有自己的额度，**Ship 不附送审查服务或免费额度**。
+可分别查看 [Copilot 审查的可用范围与计费](https://docs.github.com/en/copilot/concepts/agents/code-review)
+和 [Codex 定价与额度](https://learn.chatgpt.com/docs/pricing)。
+
+另一个原因更直接：**在我们自己的项目里，Codex review 确实找出过本地审查漏掉的错误。**
+
+例如一次修改技能的触发方式时，我们漏改了插件的默认提示。一个地方说“按任务选择角色”，
+另一个地方仍说“必须先走统筹”。检查通过了，本地审查也没发现，用户安装后却可能被旧提示带回原来的流程。
+Codex review 指出了这个矛盾，修复后才完成合并。这是我们继续使用它的理由，不是模型优劣的对照测试。
+
+本地 Reviewer 和 GitHub Codex review 可以分别使用：前者在写代码的现场帮忙检查，后者在 PR 上留下
+审查结果。Ship 自己两层都用，采用它的项目可以按需要选择。
+
+### 用 AGENTS.md 告诉 Codex：这个项目最容易错在哪里
+
+Codex review 会读取仓库中适用于改动文件的 `AGENTS.md` 指引。全项目规则写在仓库根目录；
+只适用于某个模块的规则写在该模块的 `AGENTS.md`。适用范围由文件位置决定，不靠某个标题开启。
+审查专用规则可以按官方建议集中放在 **`## Code Review Rules`** 下，方便维护；其他标题下的适用指引
+仍然有效。添加下面的例子前，先检查已有规则，避免重复或冲突。
+只放在自己电脑上的个人指引，不能当作 GitHub 上的审查配置。
+[OpenAI 官方说明](https://learn.chatgpt.com/docs/third-party/github#customize-what-codex-reviews)
+介绍了读取范围和写法。
+
+假设你的项目是一个多人使用的书签应用，可以从这几条开始。**请按自己的业务改写，不要原样套到所有项目。**
+
+```markdown
+## Code Review Rules
+
+- 书签查询必须限制在当前用户的数据范围内。新增搜索、导出或批量接口也要检查；
+  只有明确的管理员接口可以跨用户，并且必须保留管理员权限校验。
+- 数据格式变化后，旧版本保存的书签仍应能读取。若这次明确要求迁移，检查迁移和失败恢复路径，
+  不要把已有用户的数据当成可以丢弃的测试数据。
+- 报告会影响行为、兼容性或任务范围的具体问题，并指出出错条件。
+  格式问题交给 lint；仅为可能的未来需求增加通用层，不作为必须实施的修复。
+```
+
+“帮我严格检查”没有告诉审查者什么是重要的；“搜索不能查到别人的书签”才给了它可以核对的规则。
+先写两三条经常需要你提醒的事，用实际 PR 看它是否有帮助。无关改动也被反复挑错，就收窄或删掉那条规则。
+更多例子见 OpenAI 的 [Custom Code Review rules](https://developers.openai.com/blog/custom-code-review-rules-for-codex)。
+
+### 接 Gate 前，先知道这三件事
+
+**第一，当前仓库选择评论触发。** 负责 PR 交付的 Writer 对每个待审新提交，在 PR 评论：
+
+```text
+@codex review
+```
+
+这个选择记录在 `.ship.yml` 的 `review.codex.trigger: comment`。采用方也可明确选择 `automatic` 或 `none`；
+同一提交已有请求、进行中状态或有效结果就复用，不因等得久而重复发送。评论触发时不要再叠加自动审查：
+我们曾实测自动审查只留下 PR 上的 👍，显式请求才给出带提交标记的评论。历史记录与修复见
+[这个坑的完整经过](docs/lessons-learned.md#1-自动审查和显式请求曾返回不同证据)。
+
+**第二，Gate 看的是审查结果，不是代码本身。** 它不会发现 Codex 漏掉的 bug，也不会替你判断产品好不好用。
+
+| PR 上的情况 | Gate 如何处理 |
+| --- | --- |
+| 当前提交的审查结果还没齐 | 等待，不借用上一版的绿灯 |
+| 当前提交有有效的 clean 结果 | `codex` 检查通过 |
+| 当前提交有有效的问题报告 | `codex` 检查失败，先核实并处理问题 |
+| 网络、权限或结果格式出了故障 | 查看工作流错误；故障不能当成代码缺陷，也不能算通过 |
+
+**第三，Gate 由你配置和持有。** 它运行在你的 GitHub Actions 中。你需要接入 Codex review，创建自己的
+GitHub App，把私钥放入受限 Environment，再在 Ruleset 中要求该 App 发布的 `codex` 检查通过。
+安装器只准备文件，不替你创建账号、读取凭据或改合并规则。
+
+App 每次运行的短期令牌只申请当前仓库的 Checks write，用于发布检查；注册层另有 GitHub 选择检查来源
+所需的 Commit statuses read/write。工作流读取 PR 的令牌是只读的。**这套接入有明确的权限，不能叫
+“零权限”**；私钥由你保管，Ship 作者不代持。Ship 自带的反馈入口帮助执行者等待并接收 CI 结果。
+
+准备接入时再看 [Gate 配置指南](docs/gate-adoption.md)，里面列明对象、权限和每项保护带来的等待。
+只想使用角色协作方法，可以先跳过 Gate。
+
+
+## 怎样用好 Ship
+
+自动化有一种很容易被忽略的成本：它可以把一个含糊的要求执行得非常认真。
+
+“把搜索做好”可能先变成全文检索，再变成可切换的搜索后端，接着需要配置、缓存和同步。每一步都能找到
+局部理由，最后却多出了一套你从未打算维护的东西。代码写得工整、测试覆盖充分，都不能回答最开始那个
+问题：这个项目现在需要它吗？
+
+所以 Ship 很看重任务合同。这个词听起来正式，实际可以是一段普通的话，把目标、范围、验收方式和需要
+重新讨论的地方说清楚。无需为了修一个按钮先写一份项目计划。
+
+例如，在一个已有的书签页面上增加搜索：
+
+```text
+给书签列表加一个标题搜索框，方便我在当前已加载的书签里找内容。
+
+沿用页面已有的组件和数据，只做前端筛选。这次不做服务端搜索、标签搜索和语义搜索，
+不增加依赖，不改存储结构。
+
+搜索忽略英文字母大小写；清空关键词后恢复完整列表；没有匹配结果时显示提示。
+筛选不能修改原来的书签数据。沿用现有页面风格，我要能在页面上直接试用。
+
+完成相关修改和项目要求的检查，说明实际验证了什么、还有什么没验证。
+如果你发现现有数据不足以实现这个范围，先给出证据和可选方案，再决定要不要扩大需求。
+
+这次交付一个 PR 供我查看，先不合并或部署。范围内的问题继续修复；已有检查通过后，
+没有新的改动或问题，就不要反复重跑或顺手扩展功能。
+```
+
+这里最有用的几句话往往是“当前已加载”“只做前端筛选”和“先不合并”。它们让实现者知道这一轮走到
+哪里算完成，也让审查者有依据判断有没有做偏。至于组件放在哪里、怎样复用现有函数，可以留给 Agent
+看过代码后决定。
+
+合同里还可以写成本上限、兼容范围和真实用户。一个只给自己用的小工具，与必须兼容多年历史数据的服务，
+需要的实现可能差很多。不要让 Agent 在信息空白处替你假设出一个大型产品。
+
+当然，把文字写清楚也不是一次性保险。开始做之后发现事实不符，就调整目标或方案。需要避免的是在没有
+新证据时，把审查建议、研究中见到的做法和想象中的未来需求悄悄加进本轮工作。长期规则放在项目的
+`AGENTS.md` 或 `CLAUDE.md`，单次任务只说明这次的差异，通常比每次粘贴一大页要求更容易维护。
+
+## 代价与局限
+
+我们愿意把 Ship 用在自己的项目里，也希望使用者知道哪些地方需要保持判断。
+
+### 多个 Agent，也可能只是把同一个错误重复几遍
+
+如果最初就误解了需求，实现、测试和审查可能一起围着错误的预期工作。一个测试若只是照着实现重新算一遍
+答案，也可能把错误固定下来。多一个角色、多一轮对话，并不自然等于多一份可靠证据。
+
+给审查者原始需求和独立的验收例子，比只给它实现者的总结更有帮助。重要的使用路径仍值得亲手试一次。
+特别是权限、数据和恢复操作，验证所用的环境是否接近真实情况，通常比报告里有几个“通过”更重要。
+
+### 审查本身也会扩大项目
+
+模型很擅长提出“还可以更稳妥”的建议：再抽一层接口，再保留一种兼容方式，再加一份记录。这些建议有时
+有用，也可能让一个已经够用的功能继续长大。
+
+Ship 要求审查意见指向具体的错误路径、可复现的输入或明确偏离的目标。写法偏好和没有证据的假想分支，
+不应该自动成为必须实施的工作。发现确实超出原范围的问题，先作取舍；不要让实现者为了让每个审查者满意，
+不断替一个小项目增加职责。
+
+审查者也可能坚持一个不成立的结论。Ship 允许拿证据处理分歧，但技术裁决不能替代外部 Gate 的通过结果。
+针对性复评后仍无法解决时，工作会停在需要决定的位置。反复请求同一版本的审查，直到某次给出绿灯，
+会让门禁失去原来的意义。
+
+### 并行会消耗更多东西
+
+每个子代理都需要阅读背景，交接会占用上下文，研究和审查会消耗额度，GitHub 上的任务可能还要排队。
+可以并行完成的独立问题值得拆；输入还没查清楚、两个任务要改同一处代码时，匆忙并行可能只会把时间花在
+等待和解决冲突上。
+
+改一个拼写错误，让当前 Agent 完成就很好。对于较大的任务，也应该能解释多开一个子任务要解决什么。
+Ship 没有一组可以普遍套用的提速或省钱数字。可以观察它有没有减少返工、有没有让你更容易理解结果，
+再决定是否继续使用。
+
+### 你仍然要维护接入它的方式
+
+Skill 中的行为约定依靠模型遵守。项目里的限制越多、重复规则越多，越需要检查它们是否互相冲突；把一份
+Skill 安装成功，也不表示每次任务都会正确选用它。角色只读约定同样不等于宿主真的收回了写入权限。
+
+Gate 还有另一层维护工作：仓库管理员需要配置 GitHub App、凭据和合并规则。Ship 的审查结果发布器使用
+固定版本的 Action，不执行 PR 中的代码；调用仓仍要妥善管理权限，并确认固定的 Action 可以访问。
+这些配置有错误，门禁就可能无法按预期工作。
+
+Ship 尽量复用宿主和 GitHub 已有的能力，没有额外的常驻服务。但宿主更新、审查结果格式变化和仓库权限
+调整，仍然可能要求重新核对接入。想要装一次就永远不用管的全自动开发，这个项目目前做不到。
+
+### 合并保护会把哪些等待带回来
+
+Gate 能减少你手工核对审查状态的工作，但不能让所有保护都没有代价。
+
+| 你选择的规则 | 日常影响 |
+| --- | --- |
+| 只对敏感路径要求负责人审批 | 改工作流、发布或检查脚本时等人；普通业务改动仍主要依赖模型和测试 |
+| 所有 PR 都需要人工批准 | 每项改动都会经过人的等待，个人开发尤其明显 |
+| 新提交使旧批准失效，或要求最新推送由他人批准 | 审查后的小修也可能需要重新批准 |
+| 合并前必须更新到最新默认分支 | 其他改动合入后，可能重跑 CI 和审查 |
+| Gate 的 Environment 每次运行都需人工放行 | 每次检查都可能停下来等人；这不是 Gate 必需的配置 |
+
+CODEOWNERS 可以标明工作流、CI 脚本、发布代码和 CODEOWNERS 文件本身由谁负责，但**只写这个文件不会
+自动强制批准**。是否要求 Code Owner review，或采用平台支持的按路径 Required reviewers，要在 GitHub 规则里
+另外选择。负责人也必须实际有权限、能参与审批，不能把“填了一个名字”当成保护已经生效。
+
+若采用敏感路径审批，应保护真正决定检查行为的文件，包括工作流调用的脚本；仅保护 YAML 不够。
+[Gate 配置指南](docs/gate-adoption.md#哪些保护值得考虑)列出了各项规则的作用与代价。Ship 不替你的项目
+开启整套规则，也不为了方便要求你关闭保护或授予绕过权限。
+
+
+### 这些限制，我们自己也踩过
+
+- 更新命令说成功，Agent 却还在读旧 Skill；现在要分清安装内容和新任务实际加载的内容。
+- 自动更新连续要求重启，反而打断正在做的工作；这套自建机制后来被删除。
+- 检查要求同一句话在三个文件重复，换个说法就报错；这些文案检查也被删除。
+
+[完整踩坑记录](docs/lessons-learned.md)还包括审查提前放行、CODEOWNERS 没有按预期阻断、Action 仍运行旧版
+等经过，并区分实际观察、测试发现和仍未查清的现象。记录保留必要技术背景，不要求访问早期私有讨论。
+
+## 后续入口
+
+### 查看、卸载与升级
+
+安装版本记录在 `项目/.ship/install.toml`。运行 `files` 查看安装清单，运行 `uninstall` 撤销项目接入；
+完整命令和兼容边界见 [安装说明](docs/install.md#查看卸载与升级)。新版安装器可处理兼容的旧安装记录。
+卸载不会撤销 GitHub 的 App、合并规则或远端 workflow，也不会卸载
+uv、Python 或清理 uv 缓存。
+
+### 常见问题
+
+**只有一个人开发，值得用吗？** 当你花很多时间追问 Agent、核对审查状态或处理交接时，可以试试。
+如果任务本来就简单，额外分工可能更慢；你也可以只用一个角色或只接 Gate。
+
+**装好以后会自动替我发布吗？** 安装器不提交、推送或发布。之后 Agent 能做什么，取决于你给当前任务的
+授权及宿主权限；长期项目规则和技能都不应替你扩大授权。
+
+**有了 Gate，就不用看代码了吗？** 它能帮助筛查缺陷、核对审查版本，不能证明需求正确、体验好或代码
+值得维护。真实使用、重要数据变更和产品取舍仍需要人参与。
+
+### 这个项目走到了哪里
+
+早期版本运行过角色协作与独立仓库 Gate 接入。这些历史结果不能替代当前公开仓的 App、Codex 连接、
+人工批准与外部采用验收；验收范围见[使用文档](docs/usage.md#冷启动验收边界)。公开源码与本地检查通过，
+也不代表 `chreode-ship` 已发布到 PyPI、GitHub Release 已归档同批产物，或所有宿主、模型组合均已验证。
+
+我们还没有足够的对照数据，证明这套分工总比单个 Agent 更快、更便宜，或者更少出错。新用户的安装便利性、
+不同任务下的技能选择，以及外部服务异常时的体验，也都需要继续改进。
+
+欢迎用一个真实的小任务判断它。完成以后，看看自己是否更清楚这次做了什么，是否少追问了几次，留下的
+代码是否愿意继续维护。如果最后只是多读了几份报告、多等了几轮审查，那这一轮就没有得到足够的收益。
+
+### 文档、问题与贡献
+
+- [使用说明](docs/usage.md)：项目安装、角色配置、独立采用与升级。
+- [自己的 Gate 怎么配置](docs/gate-adoption.md)：权限、平台对象、CODEOWNERS 和保护规则的取舍。
+- [踩坑记录](docs/lessons-learned.md)：实际发生过什么，哪些修复仍适用，哪些机制已删除。
+- [Gate 技术说明](actions/codex-review-gate/README.md)：证据判断、故障与恢复。
+- [任务提示词](docs/prompts.md)：需要更细的协作约束时参考。
+- [架构](docs/architecture.md)：组件如何连接，权限和技术限制在哪里。
+- [发布说明](docs/publishing.md)：PyPI 可信发布、GitHub Release 与同批产物验收。
+
+报告问题时，说明版本、宿主、采用的组件、操作和实际结果。日志请去除凭据与私有业务信息，不需要提交
+整个项目。后续开发与反馈统一在 `Chreode/ship` 进行。贡献代码前阅读 [本仓交付约定](.github/ship-contract.md)：
+本仓每个 `main` PR 都需要 maintainer 真人批准，新提交使旧批准失效；`lint`、`tests`、`package` 和 `codex`
+通过后仍要等待批准。[本仓 GitHub 设置](docs/setup.md)描述期望配置与验收步骤，不是消费者必须照抄的模板。
+
+[提交问题](https://github.com/Chreode/ship/issues) · [MIT License](LICENSE)