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 并不等于依赖已齐备。
