| 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
也可直接 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 无法代做）：
- 打开
chrome://extensions → 开启「开发者模式」。
- 「加载已解压的扩展程序」→ 选择
packages/chrome-extension/dist。
- 打开侧边栏 → 「本地 CLI 设置」完成检测 / 安装 / OAuth 登录。
- 拾取选区 → 输入指令 → 选择 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）。
