From 077646750bd1619ebd5cd28a38dc2f2ba26f0d1f Mon Sep 17 00:00:00 2001
From: Kaden Lau <141212002+Kenerlee@users.noreply.github.com>
Date: Sat, 9 May 2026 18:20:31 +0800
Subject: [PATCH] Add Atlas quickstart guide

Co-authored-by: multica-agent <github@multica.ai>
---
 README.md                 |   2 +-
 atlas/QUICKSTART.zh-CN.md | 324 ++++++++++++++++++++++++++++++++++++++
 atlas/README.md           |  15 +-
 3 files changed, 333 insertions(+), 8 deletions(-)
 create mode 100644 atlas/QUICKSTART.zh-CN.md

diff --git a/README.md b/README.md
index a6c0508..e3780f6 100644
--- a/README.md
+++ b/README.md
@@ -7,7 +7,7 @@
 
 两个 profile 共用本仓库的目录约定（prompts / skills / tools / autopilots / docs），但 Atlas 是按客户实例化部署的纵向产品，所有 Atlas 特有资产（OpenClaw 8 件套 + 6 个子 skill + email-extractor + boss_skill 蒸馏 demo + 客户演示 deck）封装在 [`atlas/`](./atlas/) 子目录里。Vega 的内容继续按原计划长在顶层。
 
-Atlas 部署时建议直接 `cd atlas && cat README.md` 走它的部署 SOP；本仓库根目录的下面这份 Vega 配置说明保持不变。
+Atlas 部署时建议先读 [`atlas/QUICKSTART.zh-CN.md`](./atlas/QUICKSTART.zh-CN.md)，再 `cd atlas && cat README.md` 走它的部署 SOP；本仓库根目录的下面这份 Vega 配置说明保持不变。
 
 ---
 
diff --git a/atlas/QUICKSTART.zh-CN.md b/atlas/QUICKSTART.zh-CN.md
new file mode 100644
index 0000000..1806bf6
--- /dev/null
+++ b/atlas/QUICKSTART.zh-CN.md
@@ -0,0 +1,324 @@
+# 总助 Claw 快速安装配置
+
+这份文档只解决一件事：把本仓库里的 `atlas/` 配置成一个可运行的总助 Claw / Atlas 实例。
+
+总助 Claw 是老板视角的项目执行雷达。它读取老板授权范围内的邮件和业务信号，维护项目、人员、客户状态，并输出日 Brief、周 Rollup、客户健康报告和 Andon 告警。
+
+这不是"三万同款 7 Agent / 38 技能"安装包。三万架构只作为参考，不要把写作、交易、社区、多 Bot 等通用团队能力塞进总助 Claw 的快速安装流程。
+
+## 可复制的安装配置引导词
+
+把下面这段发给负责部署的 Agent，让它按步骤引导你完成总助 Claw 配置：
+
+```text
+请帮我配置「总助 Claw」。
+
+这是 Moments 公司出品的老板视角项目执行雷达：1 个 Atlas Agent + 6 个专项技能 + 邮件抽取流水线。
+1. 请先学习 assistant-claw QuickStart：https://git.moments.top/Moments.top/assistant-claw/src/branch/main/atlas/QUICKSTART.zh-CN.md
+2. 问清：客户/老板信息、邮件接入方式、首次盘点范围、Brief 时间、告警渠道、数据边界。
+3. 请按步骤引导我完成：安装 atlas 身份文件和 skills → 初始化 state/memory/boss_skill.md → 配置 OpenClaw agents.list 和 workspace → 配置飞书 bindings → 验证。
+
+不要拉邮件，除非我明确确认邮件权限和盘点范围。
+
+🦞 Atlas 团队能力：
+- 邮件解析
+- 项目追踪
+- 人员行为观察
+- 客户雷达
+- 老板规则蒸馏
+- Brief/报告生成
+
+请开始引导我配置吧！
+```
+
+## 安装前先确认
+
+开始配置前，先向客户或部署负责人确认这些信息：
+
+| 项 | 要确认什么 |
+|----|------------|
+| 客户公司 | 公司名、行业、规模、主要工作语言 |
+| 老板信息 | 老板姓名、职位、Brief 阅读习惯 |
+| 邮件权限 | IMAP / OAuth / 转发邮箱；是否允许拉取过去 12 个月邮件 |
+| 首次盘点范围 | 默认过去 12 个月；如客户邮箱太大，先从 3 或 6 个月开始 |
+| 输出节奏 | 日 Brief 时间，默认老板本地时间 07:30 |
+| 告警渠道 | 邮件、飞书、微信机器人或仅生成报告 |
+| 数据边界 | 原始邮件是否必须留在客户网络内；谁能看到 Brief |
+
+没有这些答案时，不要开始拉邮件，也不要配置自动推送。
+
+## 目标目录
+
+推荐把客户实例放在 OpenClaw workspace 下：
+
+```bash
+export ATLAS_HOME="$HOME/.openclaw/workspace-atlas"
+mkdir -p "$ATLAS_HOME"
+```
+
+每个客户一个独立 workspace。不要让多个客户共用同一套 `state/`、`memory/`、`boss_skill.md`。
+
+## 第 1 步：安装 Atlas 配置资产
+
+在 `assistant-claw` 仓库根目录执行：
+
+```bash
+cp atlas/IDENTITY.zh-CN.md "$ATLAS_HOME/IDENTITY.md"
+cp atlas/SOUL.zh-CN.md "$ATLAS_HOME/SOUL.md"
+cp atlas/AGENTS.zh-CN.md "$ATLAS_HOME/AGENTS.md"
+cp atlas/USER.md "$ATLAS_HOME/USER.md"
+cp atlas/TOOLS.md "$ATLAS_HOME/TOOLS.md"
+cp atlas/MEMORY.md "$ATLAS_HOME/MEMORY.md"
+cp atlas/BOOTSTRAP.md "$ATLAS_HOME/BOOTSTRAP.md"
+cp atlas/HEARTBEAT.md "$ATLAS_HOME/HEARTBEAT.md"
+
+cp -R atlas/skills "$ATLAS_HOME/skills"
+cp -R atlas/mcp-tools "$ATLAS_HOME/mcp-tools"
+cp -R atlas/state-schemas "$ATLAS_HOME/state-schemas"
+```
+
+说明：
+
+- 中文部署默认使用 `*.zh-CN.md` 作为运行文件。
+- `USER.md` 是客户侧配置，必须在部署时填写。
+- `skills/` 是总助 Claw 专项能力，不是通用技能市场合集。
+
+## 第 2 步：创建运行态目录
+
+```bash
+mkdir -p "$ATLAS_HOME/state/projects"
+mkdir -p "$ATLAS_HOME/state/people"
+mkdir -p "$ATLAS_HOME/state/customers"
+mkdir -p "$ATLAS_HOME/state/runs"
+mkdir -p "$ATLAS_HOME/state/unclustered"
+mkdir -p "$ATLAS_HOME/state/audit"
+mkdir -p "$ATLAS_HOME/state/extracted"
+mkdir -p "$ATLAS_HOME/memory"
+mkdir -p "$ATLAS_HOME/boss_voice"
+```
+
+初始化 `state/index.json`：
+
+```bash
+cat > "$ATLAS_HOME/state/index.json" <<'JSON'
+{
+  "projects": [],
+  "people": [],
+  "customers": [],
+  "updated_at": null
+}
+JSON
+```
+
+初始化当天记忆：
+
+```bash
+TODAY="$(date +%F)"
+cat > "$ATLAS_HOME/memory/$TODAY.md" <<EOF
+# $TODAY
+
+## 本日运行记录
+
+- 部署初始化。
+EOF
+```
+
+初始化 `boss_skill.md`：
+
+```bash
+cat > "$ATLAS_HOME/boss_skill.md" <<'EOF'
+# boss_skill.md
+
+状态：待蒸馏
+
+首次部署后，由 `claw-boss-distiller` 读取老板过去 6 个月发出邮件，生成第一版 draft rules。
+老板审核后，才能把规则标记为 confirmed。
+EOF
+```
+
+## 第 3 步：填写客户配置
+
+编辑：
+
+```bash
+$ATLAS_HOME/USER.md
+```
+
+至少填这些字段：
+
+- Principal name
+- Role
+- Industry
+- Company size
+- Email domain
+- Primary work language
+- Daily email volume
+- Average projects in flight
+- Reads Brief on
+- Tolerance for false positives
+
+如果这些字段为空，总助 Claw 可以启动，但第一周盘点和 Brief 会缺上下文。
+
+## 第 4 步：配置 OpenClaw Agent
+
+修改 OpenClaw 配置前先备份：
+
+```bash
+cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak.$(date +%Y%m%d-%H%M%S)
+```
+
+新增 Atlas Agent：
+
+```bash
+openclaw agents add atlas --workspace "$ATLAS_HOME"
+openclaw agents list
+```
+
+如果当前环境只能有一个默认 Agent，也可以把 agent id 设为 `main`。关键是 `workspace` 必须指向 `$ATLAS_HOME`。
+
+确认 `agents.list` 里有类似结构：
+
+```json
+{
+  "id": "atlas",
+  "name": "总助 Claw",
+  "workspace": "/Users/<you>/.openclaw/workspace-atlas"
+}
+```
+
+总助 Claw 快速安装不需要创建 `writer`、`researcher`、`trader` 等子 Agent，也不需要配置 `subagents.allowAgents`。需要多 Agent 时，等单实例跑通后再做二期扩展。
+
+## 第 5 步：配置飞书入口
+
+如果使用一个飞书 Bot 接入总助 Claw，只需要把该账号绑定到 `atlas`：
+
+```json
+{
+  "bindings": [
+    {
+      "agentId": "atlas",
+      "match": {
+        "channel": "feishu",
+        "accountId": "default"
+      }
+    }
+  ]
+}
+```
+
+保留现有 `channels.feishu` 下的账号配置和访问策略，不要为了新增 binding 删除 `allowFrom`、`dmPolicy`、`groupPolicy` 等字段。
+
+配置后验证：
+
+```bash
+openclaw agents list
+openclaw channels status
+```
+
+多数配置支持热加载。只有状态没刷新、版本要求重启、或已经确认维护窗口时，才执行：
+
+```bash
+openclaw gateway restart
+openclaw gateway status
+```
+
+## 第 6 步：配置邮件抽取工具
+
+总助 Claw 的核心输入是邮件。V0 推荐先跑本地 email-extractor pipeline，确认能稳定解析样例，再接客户邮箱。
+
+```bash
+cd "$ATLAS_HOME/mcp-tools/email-extractor"
+python3 -m venv .venv
+. .venv/bin/activate
+pip install -e .
+pytest
+```
+
+如果测试通过，再接入客户邮件源：
+
+- IMAP：确认 host、port、用户名、授权码、TLS 要求。
+- OAuth：确认回调地址、client id、client secret、refresh token 存放位置。
+- 转发邮箱：确认原始 MIME 是否保留完整 header。
+
+不要把原始邮件复制出客户允许的网络边界。总助 Claw 的输出应引用邮件 ID 和规则，不暴露不相关客户或员工隐私。
+
+## 第 7 步：首次启动验收
+
+在飞书或命令入口问：
+
+```text
+你是谁？请读取你的 IDENTITY、SOUL、USER，并告诉我当前还缺哪些部署字段。
+```
+
+合格回复应满足：
+
+- 自称总助 Claw / Atlas。
+- 能说清自己是老板视角项目执行雷达。
+- 明确 V0 不替老板写信、不发信、不评价员工。
+- 能列出 `USER.md` 中未填写字段。
+
+再问：
+
+```text
+请按 BOOTSTRAP.md 给出首次部署 checklist，不要开始拉邮件。
+```
+
+合格回复应输出：
+
+- 邮件权限确认
+- 历史拉取范围
+- 日 Brief 时间
+- Andon 告警渠道
+- `state/`、`memory/`、`boss_skill.md` 初始化状态
+- W1 一次性盘点计划
+
+## 第 8 步：首次盘点流程
+
+首次盘点不要自动全量跑。先让客户确认范围：
+
+```text
+首次盘点建议拉取过去 12 个月邮件。你的邮箱量级较大时，我建议先从 3 个月试跑，确认抽取质量和误报率后再扩展到 12 个月。请确认范围。
+```
+
+确认后按顺序执行：
+
+1. `claw-email-parser`：拉取、解码、去引用、抽实体、分类意图。
+2. `claw-project-tracker`：聚类项目，生成 `state/projects/*.json`。
+3. `claw-people-observer`：生成行为观察卡，永不输出员工裁定标签。
+4. `claw-customer-radar`：生成客户健康状态和风险信号。
+5. `claw-report-writer`：生成第一份 Inventory Report。
+6. `claw-boss-distiller`：只读取老板发出邮件，生成 `boss_skill.md` draft rules。
+
+第一周交付物：
+
+- 过去 3 / 6 / 12 个月项目清单
+- Stalled / Waiting-For / Next Action 风险图
+- 客户健康清单
+- `boss_skill.md` draft，等待老板审核
+
+## 不要放进快速安装的内容
+
+这些不是总助 Claw 快速安装的一部分：
+
+- 三万同款 7 Agent / 38 技能完整团队。
+- 公众号、博客、小红书、交易、社区运营角色。
+- 多飞书 Bot 企业版配置。
+- 任意通用技能市场清单。
+- 未经确认的 `sessions_spawn` 子 Agent 调度规则。
+
+总助 Claw 的最小可用版本是一个 Atlas 实例，加上邮件抽取、项目追踪、客户雷达、人员观察、报告渲染和 boss_skill 蒸馏。先把这个闭环跑通，再谈多 Agent 扩展。
+
+## 完成话术
+
+安装完成后，给客户这样汇报：
+
+```text
+总助 Claw 已完成基础配置：
+- Agent workspace：<ATLAS_HOME>
+- 已安装身份文件、专项 skills、mcp-tools、state schemas
+- 已初始化 state、memory、boss_skill.md
+- 已绑定入口：飞书 / 其他
+- 已验证：Agent 能读取身份文件，并能输出首次部署 checklist
+
+下一步需要你确认邮件接入方式和首次盘点范围。确认后，我会先试跑小范围邮件抽取，再生成第一份项目盘点报告。
+```
diff --git a/atlas/README.md b/atlas/README.md
index 45618f4..773cb2a 100644
--- a/atlas/README.md
+++ b/atlas/README.md
@@ -25,13 +25,14 @@ Boss-perspective project execution radar. Built on the OpenClaw agent framework
 
 ## Read Order for a New Atlas Operator
 
-1. `BOOTSTRAP.md` (first run only)
-2. `SOUL.md` (boundaries — read once, internalize)
-3. `IDENTITY.md` (role)
-4. `USER.md` (boss profile, filled at deployment)
-5. `AGENTS.md` (entry points + skill roster + tool roster + autopilot)
-6. `mcp-tools/email-extractor.md` (the unsexy but critical extraction layer)
-7. `skills/README.md` then individual `SKILL.md`s
+1. `QUICKSTART.zh-CN.md` (Atlas install and first-run setup guide)
+2. `BOOTSTRAP.md` (first run only)
+3. `SOUL.md` (boundaries — read once, internalize)
+4. `IDENTITY.md` (role)
+5. `USER.md` (boss profile, filled at deployment)
+6. `AGENTS.md` (entry points + skill roster + tool roster + autopilot)
+7. `mcp-tools/email-extractor.md` (the unsexy but critical extraction layer)
+8. `skills/README.md` then individual `SKILL.md`s
 
 ## Status