setup-and-run

name	setup-and-run
description	配置并启动 doc-agent-extension —— 检查环境、安装依赖、构建扩展、启动本地 Gateway、检测官方 CLI（dws/lark-cli/ntn）状态，并把无法自动化的收尾步骤（Chrome 加载扩展、OAuth 登录）清晰交给用户。当用户说「安装 / 配置 / 启动 doc-agent-extension」「把它跑起来」「setup」「start gateway」「一键部署本地环境」时使用。

配置并启动 doc-agent-extension

本 skill 让 Agent 端到端把本仓库跑起来。核心工具是仓库里的 scripts/setup.sh（幂等、退出码可判定）。优先调用脚本，只有脚本不可用或失败时才回退到等价的原始命令。

背景（够用即可）

• 两个必须运行的部分：本地 Gateway（Node 服务，默认 127.0.0.1:19836）与 Chrome 扩展。
• 变更由本地官方 CLI 执行（钉钉 dws / 飞书 lark-cli / Notion ntn）；浏览器只做选区定位。
• 有两步必须人工：在 Chrome 里加载扩展、在浏览器完成 OAuth 授权。其余都能自动化。

标准流程

1) 一键配置 + 启动

bash scripts/setup.sh up

up 会依次执行：doctor（环境检查）→ install → build（构建扩展）→ gateway start（后台启动 + 健康检查）→ detect（检测 CLI），最后打印人工收尾步骤。

• 成功判定：命令退出码为 0，且末尾出现「配置与启动完成」。
• 若中途失败，脚本会打印失败步骤与 Gateway 日志末尾；按下面「排查」处理，不要谎报成功。

需要自定义时可分步执行：doctor / install / build / gateway start / detect [providers]。 端口或模式：GATEWAY_PORT=29836 AGENT_EXECUTION_MODE=cli bash scripts/setup.sh up。

2) 校验 Gateway

bash scripts/setup.sh gateway status   # 期望输出 executionMode:"cli"

也可直接 curl -fsS http://127.0.0.1:19836/health。

3) 解读 CLI 检测结果

detect 返回每个 provider 的安装 / 登录状态：

• 未安装：引导用户在扩展侧边栏「本地 CLI 设置」里点击「安装」，或按 CLI 参考 手动安装。
• 未登录：需要 OAuth，必须人工。提示用户在侧边栏点「登录」（授权 URL 会流式回传），或在终端运行对应命令，例如 dws auth login。
• 只检测某些 provider：bash scripts/setup.sh detect dingtalk,feishu。

4) 交接人工收尾步骤

明确告诉用户（Agent 无法代做）：

1. 打开 chrome://extensions → 开启「开发者模式」。
2. 「加载已解压的扩展程序」→ 选择 packages/chrome-extension/dist。
3. 打开侧边栏 → 「本地 CLI 设置」完成检测 / 安装 / OAuth 登录。
4. 拾取选区 → 输入指令 → 选择 Direct / Agent → 执行变更。

排查

• doctor 失败：node 需 ≥ 18；缺 pnpm 时 corepack enable 或 npm i -g pnpm。
• Gateway 起不来：bash scripts/setup.sh gateway logs 看日志；端口被占用则设 GATEWAY_PORT 换端口重试。
• 端口占用 / 残留进程：bash scripts/setup.sh gateway restart。
• detect 请求失败：多半是 Gateway 未就绪，先 gateway status 确认。
• 停止服务：bash scripts/setup.sh gateway stop。

完成标准

• gateway status 返回健康且 executionMode 符合预期（默认 cli）；
• detect 至少对目标 provider 返回了状态（未登录属正常，需人工授权）；
• 已向用户交接 Chrome 加载扩展 + OAuth 两个人工步骤。

更多背景见在线文档：https://xinyuehtx.github.io/doc-agent-extension/（安装、Setup 向导、执行模式 cli/mcp）。