Skip to content

AGENTS.md

Latest commit

 

History

History
87 lines (58 loc) · 5 KB

AGENTS.md

File metadata and controls

87 lines (58 loc) · 5 KB
Raw

qkagent — 给 AI Agent 的快速说明

本仓库 qkagent.exe 通过 Playwright 操作 getquicker.net 上已分享动作的 网页简介（HTML）：可 抓取 或 上传/修改。浏览器优先使用本机 Chrome / Edge，登录态保存在本地 profile 目录，一般只需登录一次。

CLI 自描述（优先）：qkagent help --json — 命令、参数、工作流摘要。操作指南：qkagent guide get --topic workflow --json。人类可读：docs/cli-commands.md。

详细用法见 README.md。Cursor Skill：动作页说明 .cursor/skills/action-doc-workflow/SKILL.md、动作讨论 .cursor/skills/action-topics-triage/SKILL.md、CLI .cursor/skills/quicker-agent-exe/SKILL.md、发布 .cursor/skills/qkagent-publish-exe/SKILL.md。

1. 可执行文件在哪

.\publish\publish-agent.ps1

产物：<repo>\publish\agent\qkagent.exe（须保留同目录全部依赖）。

2. 配置

  1. 将 env.example 复制为 .env（与 exe 同目录或仓库根等，见程序加载逻辑）。
  2. 必填 QUICKER_EMAIL、QUICKER_PASSWORD（账号须为要编辑动作的作者）。
  3. 可选：
    • QKAGENT_HEADLESS：默认 true（无界面、不占焦点）；设为 false 时以最小化窗口运行便于调试。
    • QKAGENT_PROFILE_DIR：浏览器 profile（cookies）；默认 %LOCALAPPDATA%\qkagent\browser-profile。
    • QKAGENT_BROWSER_CHANNEL：强制 chrome / msedge / chromium；默认依次尝试 Chrome → Edge → Playwright Chromium。

若本机无 Chrome/Edge，发布脚本安装的 Playwright Chromium 可作为兜底。

3. 调用约定

动作说明在本仓库 actions/ 编写（源文件 page.html，提交 git；info.html 为构建产物）。

  • 优先 --json；退出码 0 成功，1 失败。
  • 在 tools/qkagent/ 内不要设置 QKAGENT_ACTIONS_ROOT（自动识别 <repo>/actions）。
# 推荐：编辑 actions/<sharedId>/page.html → apply（上传 info.html）
.\scripts\build-action-docs.ps1 [-Id <sharedId>]   # 可选；apply 前会自动构建
qkagent.exe apply --dir actions/<sharedId> [--json]

# pull 仅当尚无 page.html、需从线上导入时
qkagent.exe pull --code <sharedId> [--json]

禁止在 qkrpc action publish 使用 --share-note / note — getquicker「备注（已过期）」与 Detail HTML 分离；填备注会在动作页顶部重复显示。动作说明只维护 page.html → info.html。

本地根目录：存在 actions/README.md 时默认 <repo>/actions，否则 fallback 到 %USERPROFILE%\.quicker\actions。构建说明见 actions/README.md。工作流 Skill：.cursor/skills/action-doc-workflow/SKILL.md。

4. 架构要点

模块 职责
QuickerBrowserLauncher LaunchPersistentContextAsync；channel 顺序 chrome → msedge → bundled
QuickerBrowserSession 复用 profile；EnsureLoggedInAsync 检测会话，失效则自动登录
GetQuickerActionDocPage 固定 UI 文案/选择器（编辑信息、源代码、更新动作信息 等）
ActionDescriptionService GetHtmlAsync / SetHtmlAsync（登录 → 编辑信息 → 源代码视图读/写 → 更新动作信息）
ActionLocalStore 本地 actions/<sharedId>/info.html 路径与 meta.yaml
ActionTopicsService 动作讨论区 list/get/reply/archive（Share/Actions/Topics）
GetQuickerActionTopicsPage 动作讨论 URL 与 DOM 选择器

5. action-doc 抓取流程（与 Playwright MCP 手动步骤一致）

  1. 登录：EnsureLoggedInAsync；编辑页若跳转登录则自动重登（勾选「记住我」）。
  2. 打开编辑页：GetQuickerActionDocPage.EditPageUrlTemplate（/Member/Action/Edit?id={code}）。
  3. 源代码模式：点击 「源代码」，在 div.note-editor.codeview .note-editing-area textarea 读/写 HTML。
  4. 提交：点击 input.btn.btn-primary，或 form.requestSubmit()。
  5. 等待：NetworkIdle + 编辑区卸载后结束。pull/push 本地文件为 UTF-8 无 BOM。

选择器见 GetQuickerActionDocPage.cs。

6. 注意

  • 勿在日志中粘贴完整 .env。
  • 简介编辑控件仅作者可见；页面文案变更时改 GetQuickerActionDocPage.cs。

7. Cursor 用户 skill / 斜杠命令

源文件在 .cursor/skills/ 与 .cursor/commands/。同步到 %USERPROFILE%\.cursor\（可重复覆盖）：

pwsh -NoProfile -File ./scripts/install-cursor-user.ps1

publish/publish-agent.ps1 发布 exe 后会自动执行上述安装。Chat 输入 /action-info 快速操作 getquicker 动作页说明。

8. 开发者

dotnet build QuickerAgent.slnx