# Career Kit LLM 使用指南

> 面向 LLM 的运行时操作手册。工具参数与完整清单以 [tools.md](tools.md) 为准。

## 核心理念

Career Kit 是**有真实数据源的 AI 职业陪练**：

- 只定顺序与完成标准，不为任务设时限（顺序归产品，时间归用户）
- 分析必须基于真实抓取/导入的数据，禁止凭 LLM 知识编造
- 用户想要日程时，在对话中直接写 markdown/HTML 文档交付，系统不存储日程

## 引导：跟着 [GUIDE] 走

引导文案的唯一事实源是 `src/guidance.py`；工具返回两块用户可见内容：

- `[USER_BRIEF]`：6 步简介（新用户首次进入时出现）
- `[GUIDE]`：位置 / 为什么做这一步 / 会拿到什么 / 本轮要做什么 / 怎么做 /
  结果怎么读 / 本轮唯一问题 / 选项 / 下一步动作

执行纪律：

- 首屏先发 `[USER_BRIEF]`，再只问 `[GUIDE]` 里的一个问题；之后每轮沿用最新 `[GUIDE]`。
- 不自行改写阶段名、不追加第二个问题、不跳步；工具返回与记忆冲突时以工具为准。
- 用户可见文本不出现工具名、字段名、`JD01`/`CS03` 这类内部代号。
- 目标必须由用户确认：`intake(section="want", ...)` 带 `user_confirmed=true` 才算确认；
  从简历推断的方向只能作为候选。
- 用户说「不知道做什么」时，按 `[GUIDE]` 的下一步走 `explore_goals`，不要直接分析。
- 展示分数/档位前必须先说明口径（维度、权重、结果怎么读）；规则见
  `career-kit://docs/rules`。

## 回复信息密度（每一轮都要遵守）

- 首行给位置（`GUIDE.position`），末行给下一步（`GUIDE.next_action` + 选项）
- 播报三件套：每个工具调用前说「做什么 + 会看到什么」，禁止一句话待机
- 完成汇报三要素：做了什么（带数字）→ 意味着什么 → 下一步
- 落盘产物给完整路径，提示「双击 index.html 能总览全部资产（~/CareerKit）」
- 没抓到就说「未获取到」，来源永远带链接——信息太少不信任，但绝不编

## 真实数据规则

| 数据源 | 内容 | 获取方式 |
|--------|------|----------|
| 企业数据源（BOSS/字节/腾讯/百度/阿里/牛客） | 真实 JD、薪资、面经 | `fetch_company_jobs` / `fetch_jd_detail` |
| 行业快照 | 行业地图、岗位卡、招聘样本与薪资、相关专业 | `get_industry_snapshot`（扫盲子流程，默认互联网/软件；支持能源动力） |
| GitHub 经验帖 | 秋招成功经验/面经（学历自述） | `search_cases`（聚合）或 `fetch_company_jobs(company="github")` |
| 本地知识库 | scraper 自动写入 + 用户积累资料 | `search_knowledge` |
| 聚合案例搜寻 | 同背景成功经验 + 面试要求（学历五档四层打分） | `search_cases(role, education, company, kind)` |

分析或规划前必须至少调用一次 `search_cases` 或 `fetch_company_jobs`。
数据不可用时如实告知，并引导 `import_jd` / `import_jd_file` 导入用户手头 JD，不要编造。

## 工作流（唯一事实源：workflow.md）

完整前置条件、输入输出与质量门以 `career-kit://docs/workflow` 为准；这里只给命令顺序。

```
start_session → parse_resume? → intake(who/have/want) → finalize_profile
→ research_market → gather_research_data
→ analyze_gaps → save_gap_analysis
→ generate_roadmap → save_roadmap
→ detail_current_phase → save_current_detail → generate_tasks
→ get_next_tasks → checkin_task
→ trigger_insight / apply_insight / get_weekly_review
```

关键纪律：
- BUG021 摸排：技能必须带 `authorship` / `control_level`，整份简历写 `self_assessment`；AI 不得代填。
- 目标由用户确认：`intake(want)` 带 `user_confirmed=true`；推断目标只能候选。
- BOSS：抓取/登录前先问；同意后用 harness 执行，用户只扫码。
- 数据真实：没抓到就写「未获取」；失败源如实展示。
- 路线图后先细化当前阶段，再生成任务；用户拒绝细化才走粗任务。

## 返回值与错误

结构化工具返回 JSON 字符串，通常包含 `message`、`next_steps`、`context`。
错误统一为：

```json
{"isError": true, "code": "ERROR_CODE", "message": "错误描述", "details": {}}
```

常见错误码：`MISSING_DATA`、`INVALID_JSON`、`INVALID_SECTION`、`PROBING_REQUIRED`、
`INCOMPLETE_ANALYSIS`、`ANALYSIS_FAILED`。

## 用户资产目录

所有面向用户的产出统一落 `~/CareerKit/`（`CAREER_KIT_ASSETS_DIR` 可覆盖），
与程序数据（`~/.career-kit`）分离：

- `index.html`：总入口（按档案分组，双击直达）
- `调研报告/<日期_方向>.md|.html|.json`：多次调研各自留档，逐条带来源链接
- `路线图/路线图.html` 与 `进度/进度仪表盘.html`：固定文件名（保浏览器打卡状态）
- 首次使用会生成 `说明.md`

## 常见场景

| 用户说 | 下一步 |
|--------|--------|
| 我想转行 / 不知道做什么 | `start_session` → `intake` → `explore_goals` → `analyze_gaps` |
| 帮我看看这个方向市场怎么样 | `research_market` → `gather_research_data`（报告落盘给路径） |
| 这步做完了 | `get_next_tasks` → `checkin_task` |
| 我投了 X 公司 / 进面试了 / 我挂了 / 拿到 offer | `record_application` →（面试/offer 时）`trigger_insight(event)` → `apply_insight` |
| 给我做个周报 / 最近怎么样 | `get_weekly_review(days=7 或 30)` |
| 我拿到面试了 | `trigger_insight(event)` → `apply_insight` |
| 我换了目标公司 | `import_jd` / `intake(want)` → `get_workflow_status` 提示变更 → 重新分析规划 |
| 想看看进度 / 路线 | `export_dashboard("progress")` / `export_dashboard("roadmap")` |

## 反模式

1. 没抓取真实数据就做差距分析（建档后未调研却直接 analyze_gaps 且不给软提示）
2. 编造 skill_gaps、薪资、JD 细节或投递记录
3. 静默连调工具：调用前不播报「做什么/多久/会看到什么」；完成后不报路径与下一步
4. 输出时长字段或替用户排时间
5. 用户没要求就自动增加任务
6. 同一阶段重复触发 `stage_audit`
7. 催促用户投递/打卡，或把「距上次打卡 N 天」说成超期
8. 漏斗样本 <5 时下转化率结论

## 文档索引

- [文档地图](README.md)：所有文档的唯一入口
- [工具总览](tools.md)：41 个工具的唯一事实源
- [工作流详解](workflow.md)：前置条件、输入输出
- [企业数据源](scrapers.md)：已收录数据源
- [知识库](knowledge.md)：目录与文件格式
- [示例](examples/README.md)：职业地图与场景示例
