# 安装与使用

## 直接使用

1. 解压 `onboarding-kit.zip`。
2. 在 Codex、Claude Code、Cursor、GitHub Copilot、Gemini、Cline 或兼容 IDE Agent 中打开解压后的目录。
3. 如果是第一次把包交给一个新的 Agent 会话，先对 Agent 发送：`请以 BOOTSTRAP.md 的首次包接手模式启动。`
4. 如果只是启动新人引导，对 Agent 发送：`请按照 start.prompt.md 启动新人入职引导。`
5. Agent 必须先读 `AGENTS.md`、`skills/onboarding-buddy/SKILL.md` 和 `kit.yaml`；维护动作还必须读 `MAINTAINERS.md`。

首次包接手完成后，同一 Agent 会话里的后续问题应先运行 `python3 scripts/search_knowledge.py "<问题>"`，再打开命中的必要文件，不要重新全量读取整个包。

## Python 与 uv 兼容性

脚本要求 Python 3.10+。文档示例统一使用 `python3`，适用于 macOS/Linux；在 Windows 上如果没有 `python3`，请用 `python` 或 `py -3` 执行同样参数。

Agent 在运行脚本前应先探测 Python：

```bash
# macOS/Linux
python3 --version

# Windows
py -3 --version
python --version
```

如果没有 Python 3.10+，即使只是问答，也建议先让 Agent 询问是否运行 uv bootstrap。用户同意后，uv 会下载托管 Python，并让本地检索脚本正常运行。

如果用户拒绝安装、网络/权限阻断或 uv/Python 设置失败，问答场景才应急降级：让 Agent 直接读取 `search/chunks.jsonl`、`sources/source-manifest.yaml` 和命中的 module/source 文件。

如果没有 Python 3.10+，且需要维护、校验、重建索引、抓取来源或打包，必须使用 Python 3.10+ 或可选 uv bootstrap。uv bootstrap 会先检测本机 Python；如果没有可用 Python，会询问是否安装 uv。只有用户确认后才会从 uv 官方地址安装 uv，然后用 `uv run --python 3.12 python ...` 运行脚本。

```powershell
# Windows
powershell -ExecutionPolicy Bypass -File .\bootstrap.ps1
```

```bash
# macOS/Linux
sh bootstrap.sh
```

## Agent 适配入口

- Codex: `AGENTS.md`, `skills/onboarding-buddy/SKILL.md`
- Claude Code: `CLAUDE.md`
- Cursor: `.cursor/rules/onboarding-kit.mdc`
- GitHub Copilot: `.github/copilot-instructions.md`
- Gemini: `GEMINI.md`
- Cline: `.clinerules`
- 通用说明: `AGENT_COMPATIBILITY.md`

## 作为 Codex Skill 安装

推荐使用安装脚本：

```bash
python3 scripts/install_skill.py --dry-run
python3 scripts/install_skill.py
```

如果本机已经存在同名 skill，需要确认后再覆盖：

```bash
python3 scripts/install_skill.py --force
```

也可以手动将 `skills/onboarding-buddy/` 复制到本机 Codex skills 目录。

安装后，用户可说：

```text
开始新人入职引导
继续我的 onboarding
我卡在 Boss 渠道使用这一步了
PPL 怎么维护？
```

## 维护流程

1. 先读 `MAINTAINERS.md`。
2. 修改或新增 `modules/<module-id>/`，或按 `sources/README.md` 更新 sources/assets。
3. 如果没有 Python 3.10+，先用 `bootstrap.ps1` 或 `sh bootstrap.sh` 建立 uv 托管环境；安装 uv 前必须由用户确认。
4. 如果主飞书文档或嵌套资源变更，运行 `python3 scripts/ingest_lark_sources.py`。
5. 运行 `python3 scripts/validate_kit.py`。
6. 运行 `python3 scripts/index_knowledge.py`。
7. 运行 `python3 scripts/bootstrap_session.py` 生成会话包地图。
8. 用 `python3 scripts/search_knowledge.py "问题"` 验证检索。
9. 用 `python3 scripts/package_kit.py` 重新打包 zip。

## 安全要求

不要把真实密码、验证码、token、身份证号、银行卡号或完整共享账号资料放入包内。
