name: qiwei-dashboard

description: 启动并管理 Qiwei Dashboard（本地 Web 操作界面），包括真实企微 Agent、人工监管、统一技能中心和本地知识库。用于启动 4320 工作台、检查运行状态、浏览多个企微技能包、预览 Markdown/JSON/CSV/代码文件或查看房源列表与详情；必须从项目根目录运行 npm run dashboard。

Qiwei Dashboard

使用边界

本 skill 只负责：

启动本地 Dashboard Web 服务；
确认服务健康、登录状态和订阅状态；
在登录失效时引导用户恢复登录；
浏览已接入的源码版、OpenClaw、Agent Workbench 和房源匹配能力；
以只读方式预览 Agent 规则、技能说明、房源数据和运行输出；
告诉用户访问地址 http://127.0.0.1:4320/。

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

前置条件

必须位于项目目录 claude-code/claude-code-qiwe-assistant；
必须已经配置 Fmode 鉴权 token（.env.local 或环境变量 QIWEI_AUTH_TOKEN / FMODE_API_KEY）；
可选但推荐配置 QIWEI_UID；未配置时会自动生成并写入 .env.local。

启动流程

必须先切换工作目录到项目根目录，再执行启动命令：

cd claude-code/claude-code-qiwe-assistant
npm run dashboard

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

qiwei_agent_dashboard_start：启动或确认 Dashboard；
qiwei_agent_bind_controller：自动检测失败时显式绑定项目主控 Session；
qiwei_agent_status：读取账号、监听、Agent 和会话状态；
qiwei_agent_listener：启动或停止真实消息监听；
qiwei_agent_set_global：设置 paused、review、auto 或 human；
qiwei_agent_list_conversations：读取客户会话和待审核草稿；
qiwei_agent_inbox：读取前端、监听器、Agent 与人工操作事件；
qiwei_agent_generate_draft：让客户专属 Claude Code Session 生成待审核草稿，不发送。
qiwei_agent_session_guide：主动说明某客户对应的 Claude Code 会话名、所在位置和安全打开命令。

项目主控与客户会话

把客户初始化并安装技能包的文件夹视为一个独立项目边界。
项目主控 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：

npm run agent:session:list

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

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

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

服务启动后会输出：

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

技能中心与知识库

打开 http://127.0.0.1:4320/#skills 查看统一技能目录、按关键词搜索能力并切换来源包。
打开 http://127.0.0.1:4320/#knowledge 以文件夹树浏览本地知识文件；点击 properties.json 进入房源筛选、卡片列表和单套详情。
知识目录由 knowledge-base/catalog.json 配置；新增受支持的本地目录后重载页面即可扫描，不要把 Token、.env.local 或其他凭据目录加入目录表。
默认只读预览 .md、.json、.csv、.txt 和 .js；禁止通过文件节点访问配置目录之外的路径。
知识库运行输出放入 outputs/knowledge/，不要直接写入外部技能包的源码目录。

可用的只读接口：

GET /api/skills
GET /api/knowledge/tree
GET /api/knowledge/file?id=<node-id>
GET /api/knowledge/properties
GET /api/knowledge/properties/<property-id>

端口与环境变量

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

健康检查

启动后调用：

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

期望返回：

{"status":"ok"}

状态检查

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

返回示例：

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

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

常见错误

Dashboard 显示「网络请求失败」但浏览器能访问 server.fmode.cn

原因：Dashboard 启动时的工作目录不对，没有读取到 .env.local 中的 token。

解决：

cd claude-code/claude-code-qiwe-assistant
npm run dashboard

端口被占用

# Windows
netstat -ano | findstr 4320
taskkill /PID <PID> /F

# macOS / Linux
lsof -i :4320
kill -9 <PID>

文件位置

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

SKILL.md 6.2 KB Histórico Raw