内容
# HeliosHR 入职自动化
当新员工在 Workday 生效时，该系统会在整个 SaaS 堆栈（Okta、Google Workspace、Slack、Jira）中为他们配置账户和访问权限，并在失败时打开 Freshservice 工单。Claude **提出** 访问计划；确定性策略 **处理** （验证并决定是否需要人工审批）；确定性编排 **执行** 它具有完整的审计追踪。这是一个可运行的参考原型，实现了受控、边界清晰的 AI 自动化，而非生产部署。
## 理论基础（所有内容的核心思想）
**Claude 提出建议，确定性策略处理，确定性编排执行。** 大型语言模型（LLM）是一个边界清晰的决策者：它提出访问计划并编写易懂的理由，但它永远不会对访问拥有最终决定权，永远不会决定是否批准，永远不会运行无边界循环，也永远不会看到凭证。所有安全关键（审批、重试、升级）的内容都是清晰、可审计的代码。
## 运行（离线，无 API 密钥，无真实 SaaS 租户）
```bash
python3 -m venv .venv && . .venv/bin/activate
pip install -r requirements.txt
PYTHONPATH=src python -m onboarding.run
```
这将运行四个场景，从头到尾，并为每个场景打印追加审计追踪：
1. **干净加入者** - 工程权限，自动批准，在所有四个系统（Okta、Google Workspace、Slack、Jira）中配置。
2. **特权** - 涉及 `okta-admin` 的计划 **被人工持有** ；配置从未开始。
3. **重放** - 相同的入职事件到达两次；第二次传递是幂等的（无重复账户）。
4. **部分失败** - Okta 持续失败；我们重试，然后 **死信** 到 Freshservice 工单，而其他应用程序仍在配置，并将工作节点标记为可恢复（我们从未删除我们创建的账户）。
## 测试
```bash
PYTHONPATH=src python -m unittest discover -s tests
```
46 个测试覆盖了模型输出验证 + 修理循环、治理引擎（ap-payments 回归、SoD、用于组和许可证的协调防护）、跨系统配置可靠性（重试、幂等性、409 作为成功、死信）、追加审计日志和编排流程。
## 可选：实时 Claude 规划器
演示在离线时使用确定性备用规划器。要实时使用 Claude：
```bash
cp .env.example .env # 然后将您的密钥放入 .env（gitignored，永远不会提交）
# 设置 ANTHROPIC_API_KEY=...
. .venv/bin/activate && set -a && . ./.env && set +a
PYTHONPATH=src python -c "from onboarding.planner import propose_plan; ..."
```
规划器使用工具强制结构化输出，根据 Pydantic 模式验证结果，对无效输出进行一次边界修复尝试，并在模型不可用时降级为确定性备用（带有可见警告），因此模型宕机永远不会阻止入职。
## 可选：MCP 服务器
```bash
PYTHONPATH=src python -m onboarding.mcp_server
```
一个薄的 MCP 服务器，通过 stdio 暴露相同的受控配置工具（`get_worker`、`onboard_worker`、`get_onboarding_status`、`open_ticket`），因此 Claude Desktop 中的人工可以运行与管道相同的 **审计、审批** 操作，而无需持有原始 Okta 密钥。
## 已连接 vs 已指定
**已连接且可运行（垂直切片）：** Pydantic 契约、Claude 规划器（实时 + 离线备用）、确定性策略引擎（协调 + 审批 + `govern` 入口点）、跨所有四个系统（Okta create+activate 作为身份主站，Google Workspace / Slack / Jira 作为下游应用程序）的幂等配置，具有重试/回退和死信、追加审计日志、编排状态机和 MCP 服务器。所有四个都是针对真实形状的模拟（没有实时凭证，如简介所期望的）进行配置的。
**已指定，但未连接（诚实的切割清单 - “如果我有另一天”）：** 用实时应用程序 API 和 SCIM-via-Okta 替换模拟、导入的 n8n 工作流 JSON、Mover 和 Leaver 生命周期路径、计划的漂移协调和访问重新认证、机密保管库和可观察性仪表盘。每个都在技术文档中命名。
## 文档
- [docs/architecture.md](docs/architecture.md) - 架构图
- [docs/llm-examples.md](docs/llm-examples.md) - 实时 Claude 与确定性备用（LLM 获得其位置的地方）
- [docs/technical-writeup.md](docs/technical-writeup.md) - 技术文档
- [docs/executive-summary.md](docs/executive-summary.md) - 非技术所有者的执行摘要
- [docs/ai-usage-statement.md](docs/ai-usage-statement.md) - AI 使用声明
## 技术栈
Python 3.10+、Pydantic v2（验证所有模型输出）、官方 `anthropic` SDK（Claude Sonnet 4.6 规划器）和官方 `mcp` SDK / FastMCP（工具网关）。n8n 是生产中的预期编排主干（HeliosHR 的标准）；原型作为一个小型、可读的 Python 状态机流动。
## 仓库布局
```
src/onboarding/
schemas.py 规范契约（WorkerEvent、AccessPlan）
policy.py 确定性治理（协调、审批、govern）
planner.py Claude 访问规划器（实时 + 离线备用）
provisioning.py 具有重试 + 死信的幂等配置
mocks.py 真实形状的 Okta / 应用程序（Google/Slack/Jira）/ Freshservice 模拟
audit.py 追加审计日志
orchestrator.py 管道状态机
run.py 可运行的演示
mcp_server.py 受控 MCP 工具网关
tests/ 46 个单元测试
```
