kit

AI 友好的业务原子能力 CLI。kit 自带 daemon，用 playwright-core 直接拉起并管理浏览器会话。

• 命令风格：gh 风格 Object-Verb（kit <module> <resource> <verb>）
• 默认输出：单行紧凑 JSON（NDJSON 友好），便于 AI agent 直接 JSON.parse
• 浏览器命令参数面尽量对齐 playwright-cli，差异集中在 kit 的 session 管理与 JSON envelope
• 模块化扩展：新增业务在 src/modules/<name>/index.ts 实现 KitModule.register() 即可

安装与构建

npm install
npm run build      # tsc → dist/
npm link           # 把 kit 命令注册到全局
kit install        # 安装内置 Chromium，并同步到已存在的 agent skills 目录

Windows / PowerShell 下不支持 &&，请用 ; 串联：npm install; npm run build。

会话模型

kit open https://example.com              # 按 URL 自动路由并启动 daemon
kit auth https://doc.weixin.qq.com/...    # 企微授权桥：参数与 open 相同
kit open -m aio                           # 打开模块默认 URL
kit open https://example.com -s work      # 指定 session
kit list                                  # 列出 session
kit use default/work                      # 切换 active session
kit close --all                           # 关闭全部 session

kit open 若目标 <module>/<session> 已运行，会在同一 daemon 中打开本次 URL；当 --channel、--user-data-dir、--headed 等启动级参数变化时才重启实例。企微文档登录失效时，响应会通过 suggestedCommands 给出可直接执行的 kit auth ...。

全局选项

| flag | 含义 | 等价环境变量 | |------|------|--------------| | -m, --module <name> | 指定业务模块 | KIT_MODULE | | -s, --session <name> | 指定 session | KIT_SESSION | | --pretty | 多行缩进 JSON | — | | --timeout <ms> | 业务级等待上限 | — |

输出契约

成功：

{ "ok": true, "data": <业务结果>, "meta": { "module": "wecom", "command": "wecom.read", "durationMs": 123, "activeSheet": { "sheetId": "...", "sheetName": "Sheet1", "index": 0 } } }

成功响应过大时会自动落盘，stdout 只返回摘要：

{ "ok": true, "data": { "spilled": true, "outputPath": "~/.kit/outputs/20260429/aio.aio.project.page-....json", "bytes": 245321, "inlineMaxBytes": 16384, "hint": "响应过大，完整 JSON 已写入 outputPath" }, "meta": { "module": "aio", "command": "aio.project.page", "spill": { "reason": "OUTPUT_TOO_LARGE", "outputPath": "...", "bytes": 245321, "inlineMaxBytes": 16384 } } }

默认 inline 上限为 16 KiB，可用 KIT_OUTPUT_INLINE_MAX_BYTES 调整；0 表示所有成功响应都落盘。

失败：

{ "ok": false, "error": { "code": "INVALID_ARGUMENT", "message": "...", "hint": "..." }, "meta": { "module": "wecom", "command": "wecom.write", "durationMs": 17 } }

错误码与退出码（详见 src/core/errors.ts）：

| code | 退出码 | 含义 | |------|--------|------| | INVALID_ARGUMENT | 2 | 参数 / A1 表达式非法 | | MISSING_ENV | 3 | 缺少必要环境配置 | | BROWSER_NOT_AVAILABLE | 4 | 无法 connect 到 ws 端点 | | PAGE_NOT_FOUND | 5 | 找不到目标 page | | DOCUMENT_NOT_READY | 6 | SpreadsheetApp 未在时限内就绪 | | DOCUMENT_MODAL | 7 | 文档侧业务弹窗阻断 | | NOT_FOUND | 8 | 工作表 / 资源不存在 | | UNSUPPORTED_OPERATION | 9 | 不支持的操作（如跨非活动 sheet） | | CONFLICT | 10 | 切换中 / 恢复中冲突 | | TIMEOUT | 11 | 等待超时 | | CAPTCHA_FAILED | 12 | 滑块验证耗尽重试 | | INTERNAL | 1 | 未分类内部错误 |

命令树

kit wecom

工作表：

sheet list
sheet get [idOrName|index]
sheet activate <idOrName>
sheet create <name> [--position first|last|after:<id>] [--rows N] [--cols N]
sheet delete <idOrName>
sheet copy <idOrName> [newName]

读 / 写 / 清（A1 自动判别单格 / 区域；写入支持 [value] 位置参数 / --value / --data / stdin JSON）：

read  [a1] [--row N --col N] [--from-row|--to-row|--from-col|--to-col] [--sheet-id <id>]
write [a1] [value] [--value <v>] [--data <json>] [...] [--sheet-id <id>]
clear [a1] [--content-only|--style-only] [...] [--sheet-id <id>]

样式（--header [preset] 与具体样式 flag 互斥；preset list/show 只读查询）：

style [a1] --header [preset]
style [a1] --bold --italic --underline --color #FF0000 --bg #FFFF00 --font-size 12 --align left|center|right --wrap
style preset list
style preset show <name>

行 / 列结构：

row insert <n|n:n> [--count N] [--sheet-id <id>]
row delete <n|n:n> [--count N]
column insert <C|C:E> [--count N]
column delete <C|C:E> [--count N]
column resize <C|C:E> --width <px>
column auto-fit <C|C:E>

查找替换：

find <text> [--in <A1:Z100>] [--match-case] [--whole-cell] [--sheet-id <id>]
replace <text> <replacement> [--sheet-id <id>]

导出：

export [--filename <name>] [--output-dir <dir>] [--overwrite]

提醒查阅：

notice [content]

不带 content 时仅调用 /wedoc/editnotify 通知文档变更；带 content 时先通知变更，再通过 /comment/comment 发送评论。

kit aio

project page [--page N] [--size N]
sprint list <projectId>
story page <projectId> <sprintId> [--page N] [--size N]
task page <projectId> <sprintId> [--page N] [--size N]
bug page <projectId> <sprintId> [--page N] [--size N]
test-plan page <projectId> [keyword] [--page N] [--size N]
test-report page <projectId> <planId> [title] [--page N] [--size N]
test-report get <reportId>
test-report generate <projectId> <planId> [title]
test-report delete <reportId>
release-plan page <projectId> <versionNumber> [--page N] [--size N]
report sprint-week [--output <path>] [--concurrency N] [--report-ready-timeout ms] [--report-ready-poll ms]

分页型 page 命令默认 --page 1 --size 50，返回 { items, count, page, size, total, pages, hasNext, hasPrev }。sprint list 保持数组返回，因为底层接口不是分页接口。

编排示例

详见 examples/recipes/：

• wecom-write-and-export.sh — bash 版完整链路
• wecom-write-and-export.ps1 — PowerShell 版
• wecom-find-replace-and-style.sh — 找替换 + 样式

模块开发约定

1. 新模块：在 src/modules/<name>/index.ts 导出 createXxxModule(): KitModule；
2. 命令文件：放在 commands/ 子目录，每个 verb（或 verb 族）一个文件；
3. 业务命令统一通过模块 runner 执行：让 runner 负责 session 解析、RPC、错误归一、JSON 输出；命令本身只负责解析 CLI 参数；
4. 错误一律抛 KitError，给出可执行的 hint；不要直接 console.log 业务结果到 stdout（破坏 JSON 契约）；
5. 命令侧的人类可读日志走 __console（自动落 stderr）。

与 wecom-excel2 的关系

wecom-excel2 是同一份 WecomClient 的库式封装，适合在自己的 Node 脚本中 import 使用。kit 把同一能力包成 CLI 暴露给 AI agent / shell 链路，并在命令层加上 A1 双轨坐标、统一 JSON 输出与错误码。

License

MIT