---
name: qiwei-dashboard
description: 启动并预览 Qiwei Dashboard（本地 Web 操作界面），包括经营驾驶舱、真实企微 Agent、社群与客户运营、经营诊断、统一任务中心、行动效果闭环、技能中心和本地知识库。用户说“启动企微助手”“打开企微工作台”“启动并预览”时，优先调用 qiwei_agent_dashboard_start，并一次返回鉴权、席位、企微在线、白名单和监听状态；同时支持查看经营总览、诊断业务问题、管理内部任务、浏览技能包和知识文件。
---

# Qiwei Dashboard

## 使用边界

本 skill 只负责：

- 启动本地 Dashboard Web 服务；
- 确认服务健康、登录状态和订阅状态；
- 在登录失效时引导用户恢复登录；
- 浏览已接入的源码版、OpenClaw、Agent Workbench 和通用企微能力；
- 以只读方式预览 Agent 规则、技能说明、知识文件和运行输出；
- 展示经营总览、诊断证据、数据缺口、今日行动和数字员工状态；
- 在统一任务中心聚合客户跟进、目标、官方待办及文档/会议/诊断候选；
- 对已完成的诊断行动记录仅供内部使用的效果反馈；
- 告诉用户访问地址 `http://127.0.0.1:4320/`。

业务操作（群管理、客户运营、画像标签等）由用户在浏览器里完成，或通过其他专门 skill 调用 MCP 工具完成。本 skill 不替代登录、订阅、业务工具 skill。

## 前置条件

1. 在 Fmode Studio 中打开已经安装企微技能包的项目；
2. Fmode Studio 当前账号应处于登录状态，技能包会自动读取当前项目可用的 Fmode 凭据；
3. 不要求普通用户手工填写 Token、uid、guid 或接口地址。

## 启动流程

在 Claude Code 项目主控会话中，优先直接调用：

1. `qiwei_agent_dashboard_start`：启动工作台，并返回五项启动检查和下一步；
2. 根据返回结果依次处理 Fmode 鉴权、席位、企微登录、白名单和监听；
3. 打开返回的 `http://127.0.0.1:4320/#agent`。

源码开发时也可以在技能包根目录执行：

```bash
npm run preview
```

安装到客户 workspace 后，可以在项目终端执行：

```bash
node .claude/plugins/qiwei-assistant/install.js preview .
```

`preview` 会自动打开浏览器；自动打开不方便时使用 `--no-open`。端口冲突时使用 `--port 4321`。

工作台启动后的管理工具：

1. `qiwei_agent_bind_controller`：自动检测失败时显式绑定项目主控 Session；
2. `qiwei_agent_status`：读取账号、监听、Agent 和会话状态；
3. `qiwei_agent_listener`：个人版控制本地监听；企业版回调自动常驻，该工具只返回回调状态；
4. `qiwei_agent_set_global`：设置 paused、review、auto、autopilot 或 human；其中 `auto` 仅发送高置信且无需人工的回复，`autopilot` 为经二次确认后直接发送非空 Agent 回复的全自动接管，调用时需同时传 `confirmation=ENABLE_AUTOPILOT`；
5. `qiwei_agent_list_conversations`：读取客户会话和待审核草稿；
6. `qiwei_agent_inbox`：读取前端、监听器、Agent 与人工操作事件；
7. `qiwei_agent_generate_draft`：让客户专属 Claude Code Session 生成待审核草稿，不发送；
8. `qiwei_agent_session_guide`：主动说明某客户对应的 Claude Code 会话名、所在位置和安全打开命令。

## 五项启动检查

`qiwei_agent_dashboard_start` 和 `npm run preview` 必须按顺序返回：

1. Fmode 鉴权是否可用；
2. 企微席位是否有效；
3. 企微账号是否在线；
4. 测试联系人白名单是否非空；添加测试好友时自动写入白名单，普通批量加好友不自动扩大监听范围；
5. 企业版公网回调是否运行（个人版默认保持 AI 待审核监听；人工关闭时尊重关闭状态）。

只提示第一项需要处理的动作，完成后重新检查。Dashboard 只是管理界面；企业版回调和 Skill 会话读取均不依赖页面是否打开。

## 个人消息接入策略

- 手动白名单、自动纳入名单和监听开关都按当前企微账号保存在独立 Workbench DB；扫码切换账号时不得广播到其他已打开账号。当前账号运行时白名单等于该账号的手动名单与自动纳入名单并集。
- `allowlist_only` 是默认策略。未知私聊不创建会话、不写客户消息；未知群聊始终不自动纳入。
- `auto_enroll_review` 只对新私聊生效，自动写入当前账号白名单并强制会话为 `review`，不继承全局自动模式。
- `auto_enroll_autopilot` 仅在管理员输入固定确认词 `ENABLE_AUTO_ENROLL_AUTOPILOT` 后启用；新会话映射为 `autopilot`，非空 Agent 回复直接发送且不创建待审核草稿。
- `auto` 与 `autopilot` 是两个独立模式：前者保留置信度与人工风险门槛，后者只允许当前账号白名单私聊，并要求全局或单会话显式危险确认。
- 欢迎语设置字段固定为 `welcomeEnabled`、`welcomeText`、`welcomeSendMode=draft|send`，默认生成草稿。欢迎状态按账号和联系人幂等；发送失败可人工重试，进程中断留下的 `delivery_unknown` 先人工核对，不自动重复发送。

## 项目主控与客户会话

- 把客户初始化并安装技能包的文件夹视为一个独立项目边界。
- 项目主控 Claude Code 会话负责服务启动、登录、策略、审核和事件汇总，不直接承载所有客户对话上下文。
- 每个白名单客户绑定独立 Claude Code Session；Session 记录项目 ID 和主控 Session 关联，防止客户上下文互相污染。
- Dashboard、监听器、MCP 管理工具和客户 Session 共同读写 Workbench 数据库与审计事件。
- 私聊会话标题栏提供“采集当前会话”，只补采当前白名单联系人；顶部“补采全部白名单”用于批量补录。
- Claude Code 交互会话不能被浏览器页面直接异步注入消息。新事件先写入事件箱，主控会话调用 `qiwei_agent_inbox` 读取；需要自动回灌时必须由串行桥接器 resume 主控 Session，禁止并发写同一 Session。
- 客户 Session 默认只允许 Read、Glob、Grep，只生成草稿。真实发送必须继续经过白名单、模式、置信度和人工审核规则。
- Dashboard 客户标题下方必须显示 Session 状态条；识别到客户 Session 后，展示可识别名称和「查看会话与打开方式」按钮。按钮只复制安全命令，不展示原始 Session ID。

### 查看客户 Claude Code Session

先列出可识别的客户会话，不要直接读取或输出原始 Session ID：

```bash
npm run agent:session:list
```

按客户名称打开对应会话：

```bash
npm run agent:session -- --customer 王刚
```

该命令会在 Fmode Studio 当前项目终端中 resume 客户 Session，并自动 `fork-session` 为审阅副本。审阅副本保留完整历史、模型思考和工具记录；在其中查看或追问不会污染生产客户 Session。不要手工打开或传播 `outputs/messages/claude-code-sessions.json` 中的原始 ID。

服务启动后会输出：

```text
Qiwei Dashboard 已启动：http://127.0.0.1:4320/
```

## 技能中心与知识库

- 打开 `http://127.0.0.1:4320/#overview` 查看经营驾驶舱，并从客户、社群、客服和交易类问题发起只读诊断。
- 打开 `http://127.0.0.1:4320/#skills` 查看统一技能目录、按关键词搜索能力并切换来源包。
- 打开 `http://127.0.0.1:4320/#knowledge` 以文件夹树浏览本地知识文件；选择“统一任务工作台”查看正式任务、AI 候选和经营诊断行动闭环。
- 知识目录由 `knowledge-base/catalog.json` 配置；新增受支持的本地目录后重载页面即可扫描，不要把 Token、`.env.local` 或其他凭据目录加入目录表。
- 默认只读预览 `.md`、`.json`、`.csv`、`.txt` 和 `.js`；禁止通过文件节点访问配置目录之外的路径。
- 知识库运行输出放入 `outputs/knowledge/`，不要直接写入外部技能包的源码目录。

核心只读接口：

```text
GET /api/skills
GET /api/knowledge/tree
GET /api/knowledge/file?id=<node-id>
GET /api/knowledge/tasks
POST /api/business-diagnosis
```

需要内部写入的接口：

```text
POST /api/knowledge/tasks/diagnosis-candidate
POST /api/knowledge/tasks/create
POST /api/knowledge/tasks/update
POST /api/knowledge/tasks/diagnosis-feedback
```

`diagnosis-candidate` 只加入待确认候选；`create` 用于人工确认后晋升正式内部任务；`diagnosis-feedback` 只记录已完成诊断任务的内部效果。上述接口均不得被描述为已经发送客户消息，真实企微待办仍需独立确认。

## 端口与环境变量

- 默认端口：`4320`
- 可通过环境变量覆盖：`QIWEI_DASHBOARD_PORT=4320`
- 服务绑定在 `127.0.0.1`，仅本机可访问

## 健康检查

启动后调用：

```bash
curl -s http://127.0.0.1:4320/api/health
```

期望返回：

```json
{"status":"ok"}
```

## 状态检查

```bash
curl -s http://127.0.0.1:4320/api/status
```

返回示例：

```json
{
  "status": "ok",
  "summary": {
    "authConfigured": true,
    "online": true,
    "subscribed": true
  }
}
```

如果 `online: false` 且登录状态码为 `0`，Dashboard 会自动尝试免扫码恢复登录；否则需要用户在浏览器中点击「恢复登录」按钮完成扫码。

## 常见错误

### Dashboard 显示「网络请求失败」

先确认是在 Fmode Studio 当前项目中启动。客户 workspace 安装后的运行目录、输出目录和 Claude Code 工作目录应自动指向客户项目根目录，不应落入 `.claude/plugins/qiwei-assistant`。

解决：

```bash
node .claude/plugins/qiwei-assistant/install.js preview .
```

### 端口被占用

```bash
npm run preview -- --port 4321
```

启动器会校验 4320 对应的项目身份，避免误连到另一个企微项目。

## 文件位置

- 服务入口：`scripts/start-dashboard.js`
- HTTP 桥接服务：`mcp/src/dashboard/server.js`
- 前端 SPA：`mcp/src/dashboard/index.html`、`app.js`、`styles.css`