qiyu-cli 0.0.0-stage → 0.2.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +467 -2
- package/dist/cli.js +248 -0
- package/dist/commands/api.js +770 -0
- package/dist/commands/auth.js +349 -0
- package/dist/commands/credentials-source.js +70 -0
- package/dist/commands/db.js +503 -0
- package/dist/commands/local-fallback-wiring.js +67 -0
- package/dist/commands/local-fallback.js +34 -0
- package/dist/commands/query.js +564 -0
- package/dist/commands/skill-specs.js +64 -0
- package/dist/commands/skill.js +908 -0
- package/dist/commands/spec-types.js +145 -0
- package/dist/commands/stats.js +299 -0
- package/dist/commands/store-flags.js +56 -0
- package/dist/commands/store.js +258 -0
- package/dist/commands/sync-run.js +479 -0
- package/dist/commands/sync.js +757 -0
- package/dist/commands/tree.js +27 -0
- package/dist/core/config.js +259 -0
- package/dist/core/credentials.js +71 -0
- package/dist/core/edition.js +28 -0
- package/dist/core/envelope.js +201 -0
- package/dist/core/errors.js +356 -0
- package/dist/core/http.js +348 -0
- package/dist/core/ratelimit.js +126 -0
- package/dist/core/registry/index.js +212 -0
- package/dist/core/registry/params/ai.knowledge.addKnowledge.json +88 -0
- package/dist/core/registry/params/ai.knowledge.deleteKnowledges.json +46 -0
- package/dist/core/registry/params/ai.knowledge.editChannelAnswer.json +60 -0
- package/dist/core/registry/params/ai.knowledge.editKnowledge.json +95 -0
- package/dist/core/registry/params/ai.knowledge.editKnowledgeNoSimilars.json +102 -0
- package/dist/core/registry/params/ai.knowledge.getCategoryTree.json +39 -0
- package/dist/core/registry/params/ai.knowledge.getDetail.json +46 -0
- package/dist/core/registry/params/ai.knowledge.search.json +67 -0
- package/dist/core/registry/params/ai.statistic.transferHuman.json +60 -0
- package/dist/core/registry/params/category.list.json +39 -0
- package/dist/core/registry/params/chat.queue.group.query.json +39 -0
- package/dist/core/registry/params/crm.modifyOrder.json +48 -0
- package/dist/core/registry/params/crm.modifyUser.json +48 -0
- package/dist/core/registry/params/crm.syncCrmInfo.json +46 -0
- package/dist/core/registry/params/crm.tagChange.json +74 -0
- package/dist/core/registry/params/data.overview.ipcc.json +32 -0
- package/dist/core/registry/params/data.overview.session.json +53 -0
- package/dist/core/registry/params/evaluation.setting.get.json +39 -0
- package/dist/core/registry/params/event.applyStaff.json +116 -0
- package/dist/core/registry/params/event.evaluate.json +74 -0
- package/dist/core/registry/params/event.inviteEvaluate.json +81 -0
- package/dist/core/registry/params/event.qcResult.json +166 -0
- package/dist/core/registry/params/event.queryQueueStatus.json +39 -0
- package/dist/core/registry/params/event.queueEnter.json +40 -0
- package/dist/core/registry/params/event.queueLeave.json +46 -0
- package/dist/core/registry/params/event.quitQueue.json +39 -0
- package/dist/core/registry/params/event.sessionChange.json +95 -0
- package/dist/core/registry/params/event.sessionData.json +452 -0
- package/dist/core/registry/params/event.sessionEnd.json +117 -0
- package/dist/core/registry/params/event.sessionStart.json +109 -0
- package/dist/core/registry/params/event.updateUInfo.json +46 -0
- package/dist/core/registry/params/export.session.check.json +7 -0
- package/dist/core/registry/params/export.session.json +7 -0
- package/dist/core/registry/params/export.session.one.json +7 -0
- package/dist/core/registry/params/export.session.one.message.json +7 -0
- package/dist/core/registry/params/get_call_order.json +50 -0
- package/dist/core/registry/params/get_call_user_info.json +36 -0
- package/dist/core/registry/params/get_order.json +50 -0
- package/dist/core/registry/params/get_token.json +22 -0
- package/dist/core/registry/params/get_user_info.json +36 -0
- package/dist/core/registry/params/icoutcall.callIntercept.list.json +32 -0
- package/dist/core/registry/params/icoutcall.dialogFlow.fuzzySearch.json +53 -0
- package/dist/core/registry/params/icoutcall.dialogFlow.getDialogFlowList.json +32 -0
- package/dist/core/registry/params/icoutcall.get.customer.json +39 -0
- package/dist/core/registry/params/icoutcall.get.jobdetail.json +39 -0
- package/dist/core/registry/params/icoutcall.get.jobproperties.json +39 -0
- package/dist/core/registry/params/icoutcall.history.seat.json +67 -0
- package/dist/core/registry/params/icoutcall.history.team.json +67 -0
- package/dist/core/registry/params/icoutcall.job.create.json +53 -0
- package/dist/core/registry/params/icoutcall.job.importcustomer.json +46 -0
- package/dist/core/registry/params/icoutcall.job.pause.json +39 -0
- package/dist/core/registry/params/icoutcall.job.readdcustomer.json +109 -0
- package/dist/core/registry/params/icoutcall.job.start.json +39 -0
- package/dist/core/registry/params/icoutcall.job.terminate.json +39 -0
- package/dist/core/registry/params/icoutcall.phone.getLineList.json +32 -0
- package/dist/core/registry/params/ipcc.calltask.add.auto.json +117 -0
- package/dist/core/registry/params/ipcc.calltask.add.byCustom.json +96 -0
- package/dist/core/registry/params/ipcc.calltask.add.byRelation.json +82 -0
- package/dist/core/registry/params/ipcc.calltask.add.toGroup.json +89 -0
- package/dist/core/registry/params/ipcc.calltask.add.toStaff.json +89 -0
- package/dist/core/registry/params/ipcc.calltask.get.json +47 -0
- package/dist/core/registry/params/ipcc.calltaskdetail.add.json +54 -0
- package/dist/core/registry/params/ipcc.calltaskdetail.delete.json +40 -0
- package/dist/core/registry/params/ipcc.calltaskdetail.get.json +54 -0
- package/dist/core/registry/params/ipcc.calltaskdetail.update.json +40 -0
- package/dist/core/registry/params/ipcc.customfield.template.get.json +47 -0
- package/dist/core/registry/params/ipcc.login.json +47 -0
- package/dist/core/registry/params/kefu.add.json +130 -0
- package/dist/core/registry/params/kefu.delete.json +39 -0
- package/dist/core/registry/params/kefu.update.json +137 -0
- package/dist/core/registry/params/kefu.v2.query.json +39 -0
- package/dist/core/registry/params/kefuGroup.add.json +39 -0
- package/dist/core/registry/params/kefuGroup.delete.json +39 -0
- package/dist/core/registry/params/kefuGroup.update.json +46 -0
- package/dist/core/registry/params/kefuGroup.updateKefus.json +46 -0
- package/dist/core/registry/params/merchant.account.login.json +53 -0
- package/dist/core/registry/params/merchant.changePassword.json +46 -0
- package/dist/core/registry/params/merchant.create.json +81 -0
- package/dist/core/registry/params/merchant.disable.json +39 -0
- package/dist/core/registry/params/merchant.enable.json +39 -0
- package/dist/core/registry/params/merchant.list.json +46 -0
- package/dist/core/registry/params/merchant.query.json +46 -0
- package/dist/core/registry/params/merchant.update.json +74 -0
- package/dist/core/registry/params/message.send.image.json +53 -0
- package/dist/core/registry/params/message.send.json +53 -0
- package/dist/core/registry/params/message.send.voice.json +53 -0
- package/dist/core/registry/params/message.sendFile.json +39 -0
- package/dist/core/registry/params/message.uploadFile.json +39 -0
- package/dist/core/registry/params/online.session.category.list.json +39 -0
- package/dist/core/registry/params/online.session.customfield.template.json +39 -0
- package/dist/core/registry/params/online.session.customfield.update.json +74 -0
- package/dist/core/registry/params/order.upload.json +40 -0
- package/dist/core/registry/params/push.msg.image.json +74 -0
- package/dist/core/registry/params/push.msg.richText.json +74 -0
- package/dist/core/registry/params/push.msg.text.json +74 -0
- package/dist/core/registry/params/receive.message.json +89 -0
- package/dist/core/registry/params/robot.data.getQuestionsByCategoryName.json +67 -0
- package/dist/core/registry/params/robot.data.knowledge.json +46 -0
- package/dist/core/registry/params/robot.data.kpoint.json +46 -0
- package/dist/core/registry/params/robot.data.queryStandardByEffectiveQuestion.json +46 -0
- package/dist/core/registry/params/robot.data.queryStandardQuestionList.json +46 -0
- package/dist/core/registry/params/robot.evaluation.comment.json +67 -0
- package/dist/core/registry/params/robot.evaluation.setting.json +46 -0
- package/dist/core/registry/params/robot.session.assist.json +74 -0
- package/dist/core/registry/params/robot.session.chat.json +74 -0
- package/dist/core/registry/params/robot.session.close.json +53 -0
- package/dist/core/registry/params/robot.session.commonQuestions.json +74 -0
- package/dist/core/registry/params/robot.session.create.json +81 -0
- package/dist/core/registry/params/robot.session.evaluation.json +67 -0
- package/dist/core/registry/params/robot.session.msgAssociate.json +46 -0
- package/dist/core/registry/params/robot.session.msgEvaluation.json +53 -0
- package/dist/core/registry/params/robot.session.msgPredict.json +74 -0
- package/dist/core/registry/params/robot.session.transfer.json +36 -0
- package/dist/core/registry/params/robot.session.uploadFile.json +32 -0
- package/dist/core/registry/params/robot.statistic.summary.json +53 -0
- package/dist/core/registry/params/robot.transfer.config.json +15 -0
- package/dist/core/registry/params/session.user.profile.json +39 -0
- package/dist/core/registry/params/settings.wxTemplates.json +46 -0
- package/dist/core/registry/params/smstask.create.json +53 -0
- package/dist/core/registry/params/smstask.status.json +39 -0
- package/dist/core/registry/params/staff.group.list.new.json +39 -0
- package/dist/core/registry/params/staff.group.members.new.json +46 -0
- package/dist/core/registry/params/staff.list.new.json +46 -0
- package/dist/core/registry/params/staff.login.json +47 -0
- package/dist/core/registry/params/statistic.overview.json +61 -0
- package/dist/core/registry/params/statistic.performance.json +82 -0
- package/dist/core/registry/params/statistic.salaryDetail.json +54 -0
- package/dist/core/registry/params/statistic.satisfaction.report.json +68 -0
- package/dist/core/registry/params/statistic.staffAttendance.json +75 -0
- package/dist/core/registry/params/statistic.staffquality.json +75 -0
- package/dist/core/registry/params/statistic.staffworklod.json +68 -0
- package/dist/core/registry/params/tag.all.json +32 -0
- package/dist/core/registry/params/tag.batchUpdate.json +32 -0
- package/dist/core/registry/params/tag.update.json +60 -0
- package/dist/core/registry/params/ticket.apply.json +46 -0
- package/dist/core/registry/params/ticket.batch.modify.json +53 -0
- package/dist/core/registry/params/ticket.create.json +151 -0
- package/dist/core/registry/params/ticket.filter.count.json +46 -0
- package/dist/core/registry/params/ticket.filter.list.json +46 -0
- package/dist/core/registry/params/ticket.finish.json +60 -0
- package/dist/core/registry/params/ticket.followers.update.json +60 -0
- package/dist/core/registry/params/ticket.list.json +74 -0
- package/dist/core/registry/params/ticket.log.json +39 -0
- package/dist/core/registry/params/ticket.modify.json +74 -0
- package/dist/core/registry/params/ticket.new.detail.json +39 -0
- package/dist/core/registry/params/ticket.reminder.json +60 -0
- package/dist/core/registry/params/ticket.reopen.json +67 -0
- package/dist/core/registry/params/ticket.reply.json +60 -0
- package/dist/core/registry/params/ticket.search.json +116 -0
- package/dist/core/registry/params/ticket.template.fields.json +39 -0
- package/dist/core/registry/params/ticket.template.list.json +39 -0
- package/dist/core/registry/params/ticket.transfer.json +74 -0
- package/dist/core/registry/params/track.event.set.json +32 -0
- package/dist/core/registry/params/wecom.robot.switch.json +43 -0
- package/dist/core/registry/params.js +84 -0
- package/dist/core/registry/specs.json +2172 -0
- package/dist/core/registry/validate.json +11 -0
- package/dist/core/registry/validation-overrides.js +98 -0
- package/dist/core/sanitize.js +24 -0
- package/dist/core/sign.js +21 -0
- package/dist/core/time.js +194 -0
- package/dist/core/validate.js +140 -0
- package/dist/output.js +263 -0
- package/dist/postinstall.js +178 -0
- package/dist/query/errors.js +395 -0
- package/dist/query/mask.js +368 -0
- package/dist/query/metric-catalog.js +85 -0
- package/dist/query/sandbox.js +544 -0
- package/dist/query/table-query.js +297 -0
- package/dist/query/time-shape.js +44 -0
- package/dist/schedule/install.js +377 -0
- package/dist/skill/check.js +429 -0
- package/dist/skill/detect.js +371 -0
- package/dist/skill/install.js +1202 -0
- package/dist/skill/paths.js +343 -0
- package/dist/skill/qiyu/SKILL.md +92 -0
- package/dist/skill/qiyu/errors.md +55 -0
- package/dist/skill/qiyu/forbidden.md +52 -0
- package/dist/skill/qiyu/metrics.md +65 -0
- package/dist/skill/qiyu/protocols.md +55 -0
- package/dist/skill/qiyu/setup.md +50 -0
- package/dist/skill/refs.js +379 -0
- package/dist/store/config.js +137 -0
- package/dist/store/duckdb.js +321 -0
- package/dist/store/index.js +18 -0
- package/dist/store/retry.js +36 -0
- package/dist/store/schema.js +419 -0
- package/dist/store/types.js +4 -0
- package/dist/sync/day.js +8 -0
- package/dist/sync/engine.js +818 -0
- package/dist/sync/rate-gate.js +95 -0
- package/dist/sync/registry.js +22 -0
- package/dist/sync/state.js +114 -0
- package/dist/sync/tasks/dim.js +186 -0
- package/dist/sync/tasks/knowledge.js +252 -0
- package/dist/sync/tasks/pace.js +66 -0
- package/dist/sync/tasks/pipeline.js +321 -0
- package/dist/sync/tasks/reports.js +448 -0
- package/dist/sync/tasks/sessions.js +188 -0
- package/dist/sync/tasks/tickets.js +219 -0
- package/dist/sync/types.js +1 -0
- package/dist/sync/windowing.js +56 -0
- package/package.json +52 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 MisonL
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,468 @@
|
|
|
1
|
-
#
|
|
1
|
+
# qiyu-cli
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
网易七鱼(Qiyu)开放 API 的命令行封装,**主要用户是 AI Agent,人类是次要用户**。
|
|
4
|
+
|
|
5
|
+
它把七鱼官方 API 的一堆"对 Agent 不友好"之处抹平成一套可预测的契约:默认输出机器可读的
|
|
6
|
+
JSON、用退出码表达该做什么、错误按语义分类、危险操作有硬门禁。有了它,Agent 不必先学会
|
|
7
|
+
七鱼 API 的 26 种响应信封、3 种分页和一堆静默失败,就能正确调用。
|
|
8
|
+
|
|
9
|
+
> **本仓库仍在早期**:已实现「认证 + 通用 API 通道」+ API 参数校验(`api schema`/body 分级校验)+ 存储基础(见[当前状态](#当前状态))。
|
|
10
|
+
> 本地数据仓库的**同步**(`qiyu sync`)与**查询**(`qiyu db` / `qiyu query` / `qiyu stats`)均已交付,见[当前状态](#当前状态)。
|
|
11
|
+
|
|
12
|
+
## 为什么需要它
|
|
13
|
+
|
|
14
|
+
七鱼官方 API 对自动化调用者有几个系统性的坑,而且大多是**静默**的——不报错,只是答案错了:
|
|
15
|
+
|
|
16
|
+
| 问题 | 具体表现(均来自只读实测) |
|
|
17
|
+
|---|---|
|
|
18
|
+
| 响应信封不统一 | `message` 字段的类型横跨 string / object / integer / boolean / array;同一段文本既可能是错误信息,也可能是要二次解析的 JSON 载荷 |
|
|
19
|
+
| 分页三套并存 | 游标(`mid`+`isEnd`)、页码(`curPage`/`page`/`offset`)、以及完全不分页;大多数接口不返回 `total` |
|
|
20
|
+
| 错误码语义重叠 | 同一错误码(如 `14500`)承载多种含义,靠码分派必然出错;必须按 `message` 精确文本分派 |
|
|
21
|
+
| 静默失败 | 时间参数传错单位 → `code:200` 但字段全是 `-1`;`opEnd` 缺省 → 静默返回全量;`robotId` 被静默忽略 |
|
|
22
|
+
| 危险操作无区分 | 写接口与读接口在文档里长得一样,误调用不可逆 |
|
|
23
|
+
|
|
24
|
+
`qiyu-cli` 把这些差异收敛到一个稳定的 CLI 契约里,并让每一次失败都能被 Agent 程序化地处理。
|
|
25
|
+
|
|
26
|
+
## 安装
|
|
27
|
+
|
|
28
|
+
需要 Node.js ≥ 20.12(会话导出的 zip 解压依赖 `DecompressionStream('deflate-raw')`,
|
|
29
|
+
该格式 Node 20.12 起才被接受;CI 在 20.10 上实测失败后把下限钉在这里)。
|
|
30
|
+
|
|
31
|
+
```bash
|
|
32
|
+
# 作为一次性命令运行(推荐)
|
|
33
|
+
npx qiyu-cli --help
|
|
34
|
+
|
|
35
|
+
# 或全局安装
|
|
36
|
+
npm install -g qiyu-cli
|
|
37
|
+
|
|
38
|
+
# 或从源码构建
|
|
39
|
+
git clone https://github.com/MisonL/qiyu-cli.git
|
|
40
|
+
cd qiyu-cli && npm install && npm run build
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
> 核心命令(`auth`、`api`)零运行时依赖。`store` / `db` / `query` / `stats` 命令需要
|
|
44
|
+
> `@duckdb/node-api`(可选依赖,缺失时会给出安装指引)——`npm install` 会默认安装它。
|
|
45
|
+
> 该包含平台原生二进制,实测安装体积约 130 MB。`sync` 命令**零常规运行时依赖**:会话导出的加密 zip 解压走 Node 内置 `DecompressionStream`(zip 容器解析与 ZipCrypto 解密是本仓库内的实现);`fflate` 仅测试夹具合成加密 zip 用,见 `devDependencies`。
|
|
46
|
+
|
|
47
|
+
### 装完之后:安装 skill(推荐)
|
|
48
|
+
|
|
49
|
+
`qiyu` 附带一份 Agent 操作协议(skill),装到 `~/.agents/skills/qiyu` 并链接进各 Agent 的
|
|
50
|
+
skills 目录(当前支持 Claude Code 的 `~/.claude/skills` 与 Codex 的 `~/.codex/skills`)。
|
|
51
|
+
|
|
52
|
+
**当前版本,自动安装基本不会发生**,请直接跑一次:
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
qiyu skill install # 安装 / 更新 skill 正文并建链接
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
原因如实说:`package.json` 里虽有 `postinstall`,但它**只在 npm 全局安装、且不是 npx 调用时**
|
|
59
|
+
才尝试安装(判据是 `npm_config_global === 'true'` 且 `npm_command !== 'exec'`)。而
|
|
60
|
+
**npm 12 / pnpm 12 / bun 默认阻断安装脚本**;更麻烦的是,以 tarball / `file:` 方式安装时
|
|
61
|
+
npm 无法确认可信版本、也就无法 pin 版本,`--allow-scripts` 同样不生效——脚本**根本没跑**
|
|
62
|
+
(npm 仍退 0,只有一行 warn,极易被当成成功)。npx 场景下它还会主动跳过(不往你的 home 写东西)。
|
|
63
|
+
所以**不要指望 postinstall:直接运行 `qiyu skill install`**。
|
|
64
|
+
|
|
65
|
+
安装是幂等的:正文一致时不动正文(清单缺失或损坏时会补写 `.qiyu-skill.json`);要覆盖
|
|
66
|
+
你改过的正文得加 `--force`。其他子命令:
|
|
67
|
+
`qiyu skill where` 报告实体目录与各 Agent 的链接状态(只读,不修复),并给出**已安装那份
|
|
68
|
+
正文**的契约号与兼容判定(`data.entity.installed.compatible`,与 `data.cli_contract_version`
|
|
69
|
+
比较;判定不了时为 `null`,不是 `false`);`qiyu skill check`
|
|
70
|
+
校验 skill 引用的命令/表/错误 kind 是否仍存在(有违规退出码 1,CI 可跑;`--compare` 模式下
|
|
71
|
+
两份正文内容不一致、或已安装那份不可用,同样退 1)。
|
|
72
|
+
|
|
73
|
+
> 兜底提示:若 skill 未安装或已过期,`qiyu` 每次成功输出都会在 `meta.warnings` 里提醒
|
|
74
|
+
> 「未安装 / 已过期」——提示只写进 JSON,不改退出码。
|
|
75
|
+
|
|
76
|
+
## 配置凭证
|
|
77
|
+
|
|
78
|
+
凭证通过环境变量读取:
|
|
79
|
+
|
|
80
|
+
```bash
|
|
81
|
+
export QIYU_APP_KEY=你的AppKey
|
|
82
|
+
export QIYU_APP_SECRET=你的AppSecret
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
在七鱼控制台「设置 → 开放平台」可以找到这一对密钥。检查是否已配置:
|
|
86
|
+
|
|
87
|
+
```bash
|
|
88
|
+
qiyu auth whoami
|
|
89
|
+
# {"ok":true,"data":{"configured":true,"source":"env","profile":"default","robots":[]}}
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
也可以把凭证**写进配置文件**,之后就不必每次 export:
|
|
93
|
+
|
|
94
|
+
```bash
|
|
95
|
+
export QIYU_APP_KEY=... QIYU_APP_SECRET=...
|
|
96
|
+
qiyu auth login # 写入 default profile
|
|
97
|
+
qiyu auth login --profile staging # 写入指定 profile
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
`auth login` 只从**环境变量**读凭证——不接受 `--app-key`/`--app-secret`(命令行参数会留在
|
|
101
|
+
shell 历史与 `ps` 输出里)。它把配置写到 `~/.config/qiyu/config.json`(目录 `0700`、文件 `0600`),
|
|
102
|
+
合并保留该 profile 下已有的 `store`/`robots` 键,且**绝不回显**凭证(连末四位都不)。
|
|
103
|
+
配置文件是符号链接时拒绝写入(防止穿透到任意路径)。
|
|
104
|
+
|
|
105
|
+
凭证的两个来源都支持,优先级是**环境变量 > 配置文件**。两边各给一个也是合法的,
|
|
106
|
+
此时 `auth whoami` 的 `source` 报 `mixed`。
|
|
107
|
+
|
|
108
|
+
存储配置仍是**手工编辑** `~/.config/qiyu/config.json`;也可用 `--db`/`QIYU_DB_PATH` 直接指定库路径。
|
|
109
|
+
**权限规则**:配置文件**含凭证**且 group/other 可读(如 `0644`)时,所有命令都会**拒绝读取**
|
|
110
|
+
(`kind: config_insecure`,退出码 1,hint 点名要执行的 `chmod`)——因为落盘的 appSecret 对同机
|
|
111
|
+
其他用户可读。不含凭证的文件维持「只在 stderr 警告、不阻断」。父目录 group/other **可写**
|
|
112
|
+
(文件可被整体替换)时同样拒绝。`auth login` 自己会把权限收紧为 `0600`,所以这条只会出现在
|
|
113
|
+
用户手工放宽之后。Windows 上跳过这些检查。数据库正常关闭后 `.wal` 临时文件会自动消失,请勿手工删除。
|
|
114
|
+
|
|
115
|
+
> ⚠️ `whoami` **只检查凭证是否存在**,不校验它是否有效——一个拼错的 AppKey 同样返回
|
|
116
|
+
> `configured: true`。第一次真实调用才是唯一的验证。
|
|
117
|
+
>
|
|
118
|
+
> `whoami` 输出的 `robots` 来自配置里的 `profiles.<name>.robots`(`{"1000001":"机器人A"}` 形态),
|
|
119
|
+
> 同样**未校验有效性**。它是 `sync run` 的兜底来源:`store.options.knowledgeRobotIds` 缺席时,
|
|
120
|
+
> 知识库类目同步会用这些 id 驱动(`knowledgeRobotIds` 优先)。
|
|
121
|
+
|
|
122
|
+
## 使用
|
|
123
|
+
|
|
124
|
+
```bash
|
|
125
|
+
# 列出可主动调用的接口
|
|
126
|
+
qiyu api list
|
|
127
|
+
|
|
128
|
+
# 连同不可主动调用的接口(入站推送等)一起列出
|
|
129
|
+
qiyu api list --all
|
|
130
|
+
|
|
131
|
+
# 调用一个接口
|
|
132
|
+
qiyu api call ticket.search --body '{"opStart":1730000000000,"opEnd":1730100000000}'
|
|
133
|
+
|
|
134
|
+
# 危险接口(写/破坏性操作)必须显式确认
|
|
135
|
+
qiyu api call message.send --body '{...}' --yes
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
### 命令一览
|
|
139
|
+
|
|
140
|
+
```
|
|
141
|
+
qiyu auth whoami 检查凭证是否已配置(来源/robots)
|
|
142
|
+
qiyu auth login [--profile <name>] 把环境变量里的凭证写入配置文件
|
|
143
|
+
qiyu api list [--all] 列出接口
|
|
144
|
+
qiyu api call <id> [--body <JSON>] [--yes] [--no-validate] [--strict]
|
|
145
|
+
调用接口
|
|
146
|
+
qiyu api schema <id> 查看接口参数表与响应形状
|
|
147
|
+
qiyu store init [--db <path>] [--profile <name>] [--backend <name>]
|
|
148
|
+
初始化本地数据库(DuckDB)
|
|
149
|
+
qiyu store status [--db <path>] [--profile <name>] [--backend <name>]
|
|
150
|
+
查看数据库状态与各表行数
|
|
151
|
+
qiyu sync tasks 列出全部同步任务(含敏感列清单)与不支持的数据集
|
|
152
|
+
qiyu sync run [任务...] [--full] [--since T] [--until T] [--quiet]
|
|
153
|
+
同步数据进本地库(缺省全部任务;进度走 stderr)
|
|
154
|
+
qiyu sync status [任务...] 水位、区间状态(resolved_range)、缺口(gaps)、锁
|
|
155
|
+
qiyu sync verify [任务...] 核对本地与远端一致性(drift 非空退出码 1)
|
|
156
|
+
qiyu sync install --schedule CRON [--yes]
|
|
157
|
+
安装系统调度条目(默认 dry-run)
|
|
158
|
+
qiyu sync uninstall [--yes] 移除系统调度条目(默认 dry-run)
|
|
159
|
+
qiyu db tables 本地表清单 + 粒度 + 行数 + 数据时间范围 + PII 列
|
|
160
|
+
qiyu db describe <表> 列名/类型/可空/敏感标记/观测枚举/时间列/单位
|
|
161
|
+
qiyu query --sql <SQL> 任意只读 SQL(三层沙箱 + 默认脱敏 + 行数上限 + 超时)
|
|
162
|
+
qiyu query --table <表> [--since T] [--until T] [--group-by <列>]
|
|
163
|
+
受约束查询通道(列白名单、时间列语义化、精确脱敏)
|
|
164
|
+
qiyu stats fields <报表> 指标自描述(声明 + 本地观测分布 + -1 哨兵)
|
|
165
|
+
qiyu skill install [--dir <path>] [--link <agent>]... [--no-link] [--force] [--dry-run]
|
|
166
|
+
安装 skill 正文并链接进各 Agent 的 skills 目录
|
|
167
|
+
qiyu skill check [--installed [--dir <path>] | --compare [--dir <path>]]
|
|
168
|
+
校验 skill 引用的命令/表/错误 kind(有违规退出码 1;
|
|
169
|
+
--compare 下内容不一致也算失败)
|
|
170
|
+
qiyu skill where [--dir <path>] 报告实体目录与各 Agent 链接状态(只读,不修复),
|
|
171
|
+
并报已安装正文的契约号与 compatible 判定
|
|
172
|
+
qiyu --version 包版本 + skill_contract_version
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
## 输出契约
|
|
176
|
+
|
|
177
|
+
这是本项目的核心。Agent 靠**退出码**和 **stdout 的 JSON** 做决定,不解析人类文本。
|
|
178
|
+
|
|
179
|
+
### 成功
|
|
180
|
+
|
|
181
|
+
```json
|
|
182
|
+
{"ok":true,"data":<接口载荷>,"meta":{...}}
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
三个键恒在。`data` 即使为空也写成 `null`(不会整个消失),这样 Agent 能区分
|
|
186
|
+
"接口无载荷"与"我解析错了"。
|
|
187
|
+
|
|
188
|
+
### 失败
|
|
189
|
+
|
|
190
|
+
```json
|
|
191
|
+
{"ok":false,"error":{"code":"...","kind":"...","retryable":false,"message":"...","hint":"..."}}
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
**请按 `kind` 分支,不要按 `code`。** `code` 只是个标签:它可能是服务端的数字码
|
|
195
|
+
(如 `14009`),也可能是本 CLI 合成的词(`usage` / `network` / `internal` /
|
|
196
|
+
`auth_missing` / `confirm_required` / `store_locked` / `store_not_initialized` /
|
|
197
|
+
`local_rate_limit` / `query_error` / `sandbox_blocked` / `query_timeout` / `unknown`)。
|
|
198
|
+
合成词在官方错误码表里查不到;完整清单见 `qiyu --help`。
|
|
199
|
+
|
|
200
|
+
错误信封还可能有这几个**可选**键(缺省即不出现该键):
|
|
201
|
+
|
|
202
|
+
- `retry_after: {seconds, source}` —— 建议等待秒数与它的来源(`observed` 实测 /
|
|
203
|
+
`doc` 文档值 / `local` 本地令牌桶 / `fallback` 保守兜底)
|
|
204
|
+
- `retry_strategy` + `fallback` —— **只在 `api call` 撞限流、且该接口非危险操作、
|
|
205
|
+
有对应本地表、本地库文件存在时出现**:`"switch_to_local"` + 一条
|
|
206
|
+
`qiyu query --table <表>` 命令。⚠️ 表存在**不等于**已同步或覆盖你要的时间窗,
|
|
207
|
+
先 `qiyu db tables` 看行数、`qiyu sync status` 看水位再采信(`hint` 里也写了这句)
|
|
208
|
+
- `confirm_required` / `confirm_arg` / `risk` / `target` —— 退出码 4 的四件套
|
|
209
|
+
|
|
210
|
+
`api schema <id>` 的 `data.rate_limit` 是**三态**:不出现该键 = 该接口未登记在本地限频表
|
|
211
|
+
(没测过);`null` = 实测无限制;对象 = 有限频(含 `scope`,当前恒为 `endpoint`)。
|
|
212
|
+
|
|
213
|
+
### 退出码
|
|
214
|
+
|
|
215
|
+
| 退出码 | 含义 | Agent 该做什么 |
|
|
216
|
+
|---|---|---|
|
|
217
|
+
| `0` | 成功 | 读 `data` |
|
|
218
|
+
| `1` | 业务错误 | 看 `kind`/`retryable` 决定重试或上报 |
|
|
219
|
+
| `2` | 用法错误 | 改参数重来(`--strict` 误拒除外——那是本地参数表未收录,不要删字段重试) |
|
|
220
|
+
| `3` | 网络错误 | 退避后重试 |
|
|
221
|
+
| `4` | 需要 `--yes`(写接口仍需显式确认) | **停下来,向人类确认** |
|
|
222
|
+
|
|
223
|
+
### 用法错误是双通道的
|
|
224
|
+
|
|
225
|
+
用法错误的**同一句话**会同时写到 `stderr`(给人看)和 `stdout` 的 `{ok:false,error}`
|
|
226
|
+
(给 Agent 看)。所以无论人还是 Agent,都不会读到空输出。
|
|
227
|
+
|
|
228
|
+
### store 命令的输出
|
|
229
|
+
|
|
230
|
+
`store init` 与 `store status` 成功时输出六字段:`path` / `backend` / `config_path` /
|
|
231
|
+
`config_exists` / `schema_version` / `tables`。其中 `tables` 是 `[{name, rows}]` 数组——
|
|
232
|
+
每张表的名字与行数。`store status` 的每次调用都要对各表做全表 `COUNT`(行数无缓存),
|
|
233
|
+
轮询代价与数据量成正比,Agent 不应把它当作高频健康检查来用。
|
|
234
|
+
|
|
235
|
+
### sync 命令的输出
|
|
236
|
+
|
|
237
|
+
`sync run` 的 stdout 是 `{tasks:[...], truncated:false}`,每个任务含 `task` / `status`
|
|
238
|
+
(complete/partial/failed)/ `windows`(`{total, succeeded, failed, skipped}`,
|
|
239
|
+
`total = succeeded + failed + skipped`,`skipped` 是跳过的残段窗数,见下)/ `rows` /
|
|
240
|
+
`resolved_range`(Asia/Shanghai 的 `+08:00` ISO 二元组)/ `watermark` / `last_synced_at` /
|
|
241
|
+
`gaps` / `notes`。`gaps[].range` 与 `resolved_range` 同形态(同一套时间解析);
|
|
242
|
+
`notes` 是中文说明数组(恒在,常为空),例如「请求区间早于接口可得数据的最早边界」
|
|
243
|
+
——把「区间不可得」与「同步故障」分开。
|
|
244
|
+
|
|
245
|
+
**`ok` 与退出码的双轨语义**:`ok:true` 表示「命令已产出结果」,**退出码才是成败的权威
|
|
246
|
+
判据**。全失败(退出码 1)与 `sync verify` 的 drift 非空(退出码 1)时 stdout 仍是
|
|
247
|
+
`{ok:true,data:...}`——缺口/漂移就是它要报告的内容。请先看退出码,再看 `data`。
|
|
248
|
+
|
|
249
|
+
`sync status` 每任务输出 `{task, watermark, range_status, last_synced_at, resolved_range,
|
|
250
|
+
gaps, gaps_count, locked}`:`resolved_range` 是上次成功推进覆盖的区间(形态同 run 的
|
|
251
|
+
`resolved_range`),`gaps` 是历史缺口逐条 `{range, reason, detail, recorded_at}`。
|
|
252
|
+
`sync verify` 输出 `{task, local_rows, expected_from_api, state_windows_consistent, drift}`:
|
|
253
|
+
**`expected_from_api` 只对快照任务有意义**(上游 fetch 的行数);windowed 任务不做上游
|
|
254
|
+
全量重拉,该字段恒为 `null`,核对方式是「本地行数 ↔ sync_state 成功状态」的一致性
|
|
255
|
+
(`state_windows_consistent`)——两种任务的核对方式不同,读 drift 前先看任务 kind。
|
|
256
|
+
`sync tasks` 每任务含 `sensitive_columns`——该表标注为敏感的 PII 列清单(会话/工单的
|
|
257
|
+
`payload` 列在列内,它是整行 PII 的完整副本,不要 `SELECT *`)。本阶段**没有**任务的
|
|
258
|
+
启用/停用机制:注册表里的任务总是全部执行(选定任务靠命令行显式列出)。
|
|
259
|
+
|
|
260
|
+
**聚合报表按天切片(窗口 1 天)**:九个报表接口返回的是**窗口聚合值**(`overview` 一行
|
|
261
|
+
全局汇总、`staffworklod` 每客服一行、`transferHuman` 恒 1 行),响应里的 `date` 原文是
|
|
262
|
+
"this date has no specific meaning, it only indicates the start time of the current query"
|
|
263
|
+
——多天窗口会把 N 天汇总标成某一天(`daily_overview` 的「每日概览」会读到 31 天累计值)。
|
|
264
|
+
所以窗口上限是 **1 天**(唯一例外:`staff_attendance`/考勤响应逐行带可信小时戳,保持
|
|
265
|
+
31 天窗口、`stat_date` 按该行时间戳推导)。**代价如实写在明处:窗口数 = 天数**,
|
|
266
|
+
`sync run --full` 对报表任务会从 1970 起切出**上万窗**(≈ 56 年 × 每天 1 窗,每窗至少
|
|
267
|
+
一次调用)——首跑与回补历史请用 `--since/--until` 限定区间(如 `--since 30d` = 30 窗/任务)。
|
|
268
|
+
|
|
269
|
+
**窗口端点按上海日界对齐**:8 个 `stat_date` 为主键的报表任务(考勤除外)的窗口对齐
|
|
270
|
+
上海自然日 0 点(`windowAlign: 'shanghaiDay'`)——水位续跑(`watermark+1ms`)或任意时刻
|
|
271
|
+
`--since` 产生的「错相位窗」(如 `[今天18:23, 明天18:23)`)只写一行 `stat_date` 却装着
|
|
272
|
+
跨两天聚合、还会把「明天」日的行删掉不重写。对齐后:**实际拉取的每窗恰是一个完整上海
|
|
273
|
+
自然日**,按日增量的「每日概览」日行恒为全天值。**显式区间的非日界首末段是残段窗**(如
|
|
274
|
+
`--since 30d` 的首段 `[起点, 次日0点)` 与末段 `[昨天0点, 终点)`、`--full` 起点钳出的
|
|
275
|
+
16 小时段)——引擎**跳过不落库**(半日聚合不写日行,避免覆盖该日的整日聚合值;
|
|
276
|
+
`windows.skipped` 如实计数、每窗一条 stderr 进度行)。**末残段**的整日值**可能**由其
|
|
277
|
+
请求区间覆盖该整天的日对齐 run 补全(水位停在最后一个整日窗末端;若下一轮的请求区间
|
|
278
|
+
仍未覆盖该整天,该段仍是残段、继续跳过——不保证「下一次 run」就补上);
|
|
279
|
+
**首残段**不落日行也**不补**——该半日段没有合法落点(写入即半日覆盖整日),属显式
|
|
280
|
+
`--since` 的边界语义(`windows.skipped` 与 stderr 进度行如实可见),要覆盖该日请给
|
|
281
|
+
更宽的 `--since`(起点落到该日 0 点或更早;`resolved_range.start` 的前缀不会自动前移)。
|
|
282
|
+
`resolved_range.start` 是**水位起点语义**(含可能被跳过的首残段前缀,≤ 1 天、不会
|
|
283
|
+
自动前移),表内首个整日行可能是 `> start` 的次日——读方按 `resolved_range`
|
|
284
|
+
的 end(水位)与 `skipped` 判断真实覆盖。
|
|
285
|
+
末窗终点被 `--until` 钳制(窗数至多多 1)。
|
|
286
|
+
|
|
287
|
+
**`sync install` 与调度环境**:调度条目不继承你的 shell 环境——launchd 的用户域不含
|
|
288
|
+
shell rc 变量。存储定位走环境变量(`QIYU_DB_PATH` 等)时,install 会把**解析出的绝对
|
|
289
|
+
路径/名称固化为调度命令的 `--db/--profile/--backend` 参数**(显式 flag 优先;只走配置
|
|
290
|
+
文件或默认值时不固化,调度任务自己读得到 HOME 下的配置文件)。若凭证走
|
|
291
|
+
`QIYU_APP_KEY`/`QIYU_APP_SECRET`,请确认其对该调度上下文可用——调度条目**不写入任何
|
|
292
|
+
凭证**(秘密进 plist/unit 文件是安全红线)。
|
|
293
|
+
|
|
294
|
+
### 查询命令的输出
|
|
295
|
+
|
|
296
|
+
五个查询命令都走同一个信封 `{ok,data,meta}`,`meta` 恒含 `warnings`(可为空数组)——
|
|
297
|
+
**0 行不等于没有数据**:**带时间过滤**而结果 0 行时,`warnings` 会说明「同步可能未覆盖该区间」,
|
|
298
|
+
而不是让你据此得出「那段时间真的没数据」。触发条件是**逐个判定的**:`--table` 通道给了
|
|
299
|
+
`--since`/`--until` 即触发;`--sql` 通道仅当 SQL 文本引用了业务时间列名
|
|
300
|
+
(`stat_date` / `work_date` / `hour_ts` / `startTime` / `endTime`)才触发——它与子句位置无关,
|
|
301
|
+
`WHERE stat_date > '…'` 也算;用**其它**列(如 `createtime`)的 `WHERE` 过滤出的 0 行不附带此警告。
|
|
302
|
+
|
|
303
|
+
`query --sql` 与 `query --table` 的 `data` 形态是 `{columns, rows}`(`rows` 为对象数组);
|
|
304
|
+
`meta` 恒含:
|
|
305
|
+
`rows`(截断后的实际行数)/ `truncated`(是否被 `--limit` 截断)/ `limit_applied`(生效上限)/
|
|
306
|
+
`masked`(本次是否脱敏)/ `masked_columns`(**实际被改写**的列名,全 null 的列不算)/
|
|
307
|
+
`mask_warnings`(脱敏缺口警告)/ `resolved_range` / `data_coverage` / `warnings`。
|
|
308
|
+
|
|
309
|
+
- `--table` 通道的输出顺序是**确定的**:无 `--group-by` 时,**有时间列的表**按时间列降序、
|
|
310
|
+
再按主键升序(`--limit` 截到的因此是**最新**的那些行);**无时间列的表**只能按主键升序。
|
|
311
|
+
有 `--group-by` 时按 `count` 降序、分组列升序。
|
|
312
|
+
- `resolved_range`:`--table` 给了 `--since`/`--until` 时回显**实际生效**的区间
|
|
313
|
+
(`+08:00` ISO 二元组),不是原始输入——`iso-day` 表会向下取整到上海自然日,
|
|
314
|
+
所以要按它判断覆盖了哪几天。`--sql` 通道恒为 `null`(任意 SQL 无法通用判定)。
|
|
315
|
+
- `data_coverage`:该表时间列在**过滤范围内**的 MIN/MAX(`+08:00` ISO);`--sql` 通道恒为 `null`。
|
|
316
|
+
它有三种 `null` 成因,用 `resolved_range` 与 `warnings` 区分:`--sql` 通道 / 该表无时间列 /
|
|
317
|
+
有过滤范围但范围内一行都没有。
|
|
318
|
+
- **`--sql` 通道的数值是 JSON 安全形态的字符串**:`COUNT(*)` / `SUM` / `BIGINT` / `HUGEINT` /
|
|
319
|
+
`DECIMAL` 一律输出字符串(如 `"n":"12"`、`"d":"1.50"`),这是驱动为避免精度丢失的取舍。
|
|
320
|
+
做算术或比较前先转数字(`Number(x)`);`--table --group-by` 的 `count`、`db describe` 的
|
|
321
|
+
`row_count`、`stats fields` 的 `observed` 则都是数字——两种口径不同,别混用。
|
|
322
|
+
- **`iso-day` 列在库内是 UTC `…Z` 形态**(上海日零点 = 前一日 16:00Z),而所有元数据出口
|
|
323
|
+
(`db tables.time_range`、`db describe` 的 `unit`、`resolved_range`、`data_coverage`)呈现
|
|
324
|
+
的是 `+08:00` 形态。`--table` 通道已处理取整语义;**`--sql` 里直接按字符串比较时要用 UTC 形态**,
|
|
325
|
+
否则会少算一天(如 `WHERE stat_date >= '2026-10-12T16:00:00.000Z'`)。检测到
|
|
326
|
+
「iso-day 列 + 日期形态字面量」时 `meta.warnings` 会明确提示。
|
|
327
|
+
- `db tables` / `db describe` 的 `meta.notice` 恒在(本库含客户 PII 的提示);
|
|
328
|
+
声明与实况不一致(缺表/缺列/多列/时间列脏值)逐条进 `meta.warnings`,不静默——`db tables` 做表级
|
|
329
|
+
与列集核对,`db describe` 给出该表的逐列差异细节。时间列里不符合约定形态的值**不进**
|
|
330
|
+
`time_range`(否则 `not-a-date` 会在字典序上赢下 MAX),并由 warning 点名数量。
|
|
331
|
+
|
|
332
|
+
`stats fields <报表>` 的输出把**声明**与**观测**分开:`declared`(每条带 `source`:
|
|
333
|
+
`design-doc` 实测 / `name-suffix` 命名推断)、`observed`(`rows_present` / `minus_one` /
|
|
334
|
+
`nulls` / `min` / `max`)、`unknown_fields`(判不出单位的字段)、`sentinel`
|
|
335
|
+
(`-1` = 该窗口或筛选条件没有匹配到数据,**不是负数比率**)。`-1` 是厂商未文档化的哨兵值,
|
|
336
|
+
`observed.minus_one` 与 `rows_present` 相等时说明该字段本次全是哨兵。
|
|
337
|
+
⚠️ 这是**聚合观测,不是逐行取值**:`rows_present` 为 1 时 `min` 与 `max` 都等于那一行的原值
|
|
338
|
+
(例:薪资明细表只有一行时,极值就是该行金额);`min`/`max` **排除 `-1` 哨兵**,因此某字段
|
|
339
|
+
全是 `-1` 时两者均为 `null`(此时看 `minus_one`)。需要逐行数据请用 `query --sql` 并自行承担
|
|
340
|
+
脱敏边界;payload 不是合法 JSON 的行不计入统计,**含空字符串键 `""` 的行仍计入该行其它字段**
|
|
341
|
+
(只跳过那个键本身),两者都会在 `meta.warnings` 里点名数量。
|
|
342
|
+
|
|
343
|
+
## 安全
|
|
344
|
+
|
|
345
|
+
- **危险操作硬门禁**:标记为 `dangerous` 的接口在缺少 `--yes` 时,**绝不发出任何请求**:body 合法则返回退出码 4,body 缺必填/非对象则**先**报参数错误(退出码 2),并给出 `confirm_required` / `confirm_arg` / `risk` / `target` 四个字段。
|
|
346
|
+
危险接口不可自动重试——避免人工确认过的不可逆操作被自动重放。
|
|
347
|
+
- **凭证绝不外泄**:`appKey` / `appSecret` / `checksum` 在所有输出(含错误消息与 stderr)中
|
|
348
|
+
都会被抹成 `<已隐藏>`。`auth whoami` 连末尾四位都不回显。
|
|
349
|
+
- **服务端内部信息过滤**:服务端偶发的错误消息里会泄漏 Java 包名/类名与请求 id,
|
|
350
|
+
透出前一律替换为占位符。
|
|
351
|
+
- **查询默认脱敏**:`query` 两条通道都默认脱敏(`sensitive: true` 的列),
|
|
352
|
+
要原始值必须显式 `--no-mask`(此时 `meta.warnings` 追加 PII 风险提示)。
|
|
353
|
+
脱敏的边界如实写在明处:`--table` 通道是**精确**的(列名来自 `TABLES` 元数据);
|
|
354
|
+
`--sql` 通道是「列名级 + 值级兜底」,**别名绕过时姓名/地址无法值级检测仍会漏**——
|
|
355
|
+
这类情形会在 `meta.mask_warnings` 里点名(是警告不是防护),要完整覆盖请用 `--table`。
|
|
356
|
+
两个已知缺口同样进 `meta.mask_warnings`,不会静默:**`--sql` 不按列名脱敏 `payload`**
|
|
357
|
+
(报表 payload 是聚合数字,整值替换会误杀;会话/工单的 payload 只靠值级检测,
|
|
358
|
+
其中的姓名/地址会原样输出——SQL 里出现 `payload`、输出含该列、或输出含整行 JSON 值
|
|
359
|
+
即警告,别名 `payload AS p`、`json_extract(payload,…)`、`row_to_json(t)` 都覆盖);
|
|
360
|
+
**`--table` 通道对 `TABLES` 之外的列不脱敏**
|
|
361
|
+
(库中多出来的列可能来自旧版 CLI,只警告不改写)。
|
|
362
|
+
⚠️ 这些是**警告不是防护**:`--sql` 通道的 payload 缺口只能靠 Agent 读到警告后改用
|
|
363
|
+
`--table` 或 `--no-mask` 显式承担风险来闭合,CLI 无法在保持报表 payload 可用的前提下
|
|
364
|
+
替你做整值替换。
|
|
365
|
+
- **只读沙箱三层缺一不可**:`query --sql` 只接受单条只读语句(`SELECT` / `DESCRIBE` / `SHOW` / `EXPLAIN`——
|
|
366
|
+
后两者实测归入 `statementType` 的 SELECT/EXPLAIN 类型值),
|
|
367
|
+
每实例首次连接时 `enable_external_access=false` + `lock_configuration=true`,
|
|
368
|
+
实例 `access_mode=READ_ONLY`。文件读写、网络、`ATTACH`、`COPY TO`、多语句全部被拦;
|
|
369
|
+
`EXPLAIN ANALYZE` 也拒(它会真正执行内层语句)。
|
|
370
|
+
|
|
371
|
+
## 当前状态
|
|
372
|
+
|
|
373
|
+
本仓库已交付设计稿中的**前六个子项目**:认证与通用 API 通道、API 参数校验
|
|
374
|
+
(`api schema`/body 分级校验)、存储层、同步引擎、查询接口与只读沙箱、Skill 化
|
|
375
|
+
(`qiyu skill install` / `skill check` / `skill where`,见上方「装完之后:安装 skill」)。
|
|
376
|
+
|
|
377
|
+
**已实现**:`auth whoami`、`auth login`(从环境变量写入配置文件,原子写 + `0600`)、`api list`、`api call`、`api schema`、完整的错误分类与脱敏、危险门禁、
|
|
378
|
+
限频感知(`retry_after`)、本地数据仓库——`store init` / `store status`(存储层已交付,
|
|
379
|
+
含 `Store` 抽象、DuckDB 后端、schema 迁移与 `store_locked`/`store_not_initialized` 错误分类)
|
|
380
|
+
与同步引擎——`sync tasks` / `sync run` / `sync status` / `sync verify` / `sync install` / `sync uninstall`
|
|
381
|
+
(21 个任务覆盖维度/报表/工单/会话/知识库数据集;增量水位、断点续跑、缺口记录、本地限频冷却持久化、
|
|
382
|
+
跨平台调度安装;会话导出走 create→poll→download→unzip→parse 流水线)。
|
|
383
|
+
`sync install` 的安装前置是**至少成功同步过一次**(sync_state 有 `range_status=complete`
|
|
384
|
+
或 `last_synced_at` 非空的行——全败的 run 只留 pending,不算跑通)。
|
|
385
|
+
查询与只读沙箱——`db tables` / `db describe` / `query --sql` / `query --table` / `stats fields`
|
|
386
|
+
(三层只读沙箱、默认脱敏、时间列三形态语义化、`-1` 哨兵呈现、声明与观测分离)。
|
|
387
|
+
Skill 化——`skill install`(复制正文 + 建 Agent 链接,幂等,`--dry-run` 只算计划)/
|
|
388
|
+
`skill check`(校验正文引用的命令、表名、错误 `kind` 与位置参数取值是否仍存在;
|
|
389
|
+
`--installed`/`--compare` 改基准;有违规退出码 1,`--compare` 下内容不一致也算失败)/
|
|
390
|
+
`skill where`(只读报告实体目录与各 Agent 链接四态:
|
|
391
|
+
`ok`/`missing`/`dangling`/`foreign`,无法判定时报 `unknown` 而非「不存在」),
|
|
392
|
+
外加 `qiyu --version`(输出包版本与 `skill_contract_version`)。
|
|
393
|
+
|
|
394
|
+
body 分级校验:`api call` 的 `--body` 与注册表参数表比对——缺必填拒绝(退出码 2),
|
|
395
|
+
未知字段/类型不符出 `meta.warnings`;`--strict` 可升级、`--no-validate` 可关闭。
|
|
396
|
+
参数表见 `qiyu api schema <id>`(`data.params`、`data.response_shape`)。
|
|
397
|
+
只依据文档生成的参数表,不构成对服务端行为的保证;**响应体不做校验**;
|
|
398
|
+
校验只对 `body_kind: json` 且有 body 参数表的接口生效,其余原样透传。
|
|
399
|
+
`--strict` 只做本地参数表闭集一致性检查(「严格」≠「正确严格」),误拒时**不要删字段重试**。
|
|
400
|
+
|
|
401
|
+
**输出格式**:所有命令默认输出紧凑 JSON(一行、可解析)。`--pretty` 输出缩进 JSON(人类可读)——
|
|
402
|
+
写在**具体子命令之后**(如 `qiyu api list --pretty`)。Agent 不需要它:默认输出已是合法 JSON,
|
|
403
|
+
缩进只是给人看的。用法错误(退出码 2)仍是紧凑 JSON —— 先修参数,再看格式。
|
|
404
|
+
|
|
405
|
+
`api list` 输出的 `meta.registry_complete` 会如实反映注册表是否已收录全部接口。
|
|
406
|
+
|
|
407
|
+
## 浏览器 / 文档
|
|
408
|
+
|
|
409
|
+
完整的接口语义、字段行为、限频与错误码的实测记录,见
|
|
410
|
+
[`docs/qiyu-cli-design.md`](docs/qiyu-cli-design.md)。
|
|
411
|
+
|
|
412
|
+
## 开发
|
|
413
|
+
|
|
414
|
+
```bash
|
|
415
|
+
npm install
|
|
416
|
+
npm run typecheck # 类型检查(含测试)
|
|
417
|
+
npm test # 运行测试(默认 4 分片并行,≈50s)
|
|
418
|
+
|
|
419
|
+
# ⚠️ 每个分片内部仍是**单进程单 worker**。vitest.config.ts 写死 maxWorkers: 1 +
|
|
420
|
+
# fileParallelism: false,分片 runner 也照传这两个参数——不要去掉。
|
|
421
|
+
# 分片数是固定值(默认 4,上限 8),不随 CPU 数放大:2026-10-05 的内存耗尽事故
|
|
422
|
+
# 根因是「无界循环 × 无界增长」,不是并发本身。
|
|
423
|
+
|
|
424
|
+
QIYU_TEST_SHARDS=1 npm test # 单片串行(≈110s,排查时序问题或复现 CI 时用)
|
|
425
|
+
npm run test:single # 等价写法
|
|
426
|
+
QIYU_TEST_SHARDS=8 npm test # 更多分片(16 核机器上收益递减)
|
|
427
|
+
QIYU_TEST_HEAP_MB=1024 npm test # 收紧每片 Node 堆上限(默认 2048)
|
|
428
|
+
```
|
|
429
|
+
|
|
430
|
+
测试覆盖了响应信封归一化、错误分类、签名、脱敏、限频、注册表校验、CLI 契约等。
|
|
431
|
+
所有对外部 API 的调用都用 mock,**测试不联网**。
|
|
432
|
+
|
|
433
|
+
CI(`.github/workflows/ci.yml`)在 push/PR 到 `main` 时对 Node 20.12(engines 下限)、
|
|
434
|
+
22(维护期 LTS)与 24(当前 LTS)跑 `npm ci` → `npm run typecheck` → `npm test`;测试并发
|
|
435
|
+
限制来自 `package.json` 的 test 脚本,CI 不另传并发参数。
|
|
436
|
+
|
|
437
|
+
除上述三步外,CI 还会在**最低版本矩阵项**跑一次**发布产物门禁**(`npm run check:pack`):
|
|
438
|
+
用 `npm pack --dry-run --json` 取真实包内容,断言 skill 正文逐篇在包内、`dist/postinstall.js`
|
|
439
|
+
存在、`dist/core/edition.js` 的版本已注入且与 `package.json` 一致。它防的是「构建脚本退化
|
|
440
|
+
(例如 build 只剩 tsc)时功能测试仍全绿、发布包却静默缺文件」——`npm test` 直接 import
|
|
441
|
+
`src/**`,从不触碰构建产物,只有这一步会。本地想跑同一条门禁:`npm run check:pack`。
|
|
442
|
+
|
|
443
|
+
### 目录结构
|
|
444
|
+
|
|
445
|
+
```
|
|
446
|
+
src/
|
|
447
|
+
cli.ts 入口与顶层分派
|
|
448
|
+
output.ts 输出契约(ok / fail / usageFail,退出码)
|
|
449
|
+
store/ 存储抽象(src/store/:Store 接口、DuckDB 后端、schema 与迁移)
|
|
450
|
+
sync/ 同步引擎(src/sync/:引擎、状态、限频门、窗口切分、任务注册表与 21 个任务)
|
|
451
|
+
query/ 查询层(src/query/:三层只读沙箱、脱敏、错误分派、表查询构造、指标目录)
|
|
452
|
+
schedule/ 跨平台调度安装(launchd / systemd / schtasks)
|
|
453
|
+
commands/ 子命令(auth / api / store / sync / db / query / stats)
|
|
454
|
+
core/
|
|
455
|
+
sign.ts 七鱼签名(checksum = SHA1(appSecret + md5(body) + time))
|
|
456
|
+
http.ts 请求构建、重试、限频
|
|
457
|
+
envelope.ts 响应信封归一化
|
|
458
|
+
errors.ts 按 message 文本的错误分类
|
|
459
|
+
credentials.ts 凭证解析与脱敏
|
|
460
|
+
ratelimit.ts 逐接口限频表
|
|
461
|
+
registry/ 接口注册表(specs.json、validate.json、params/)
|
|
462
|
+
docs/ 设计文档与实施计划
|
|
463
|
+
tests/ 测试
|
|
464
|
+
```
|
|
465
|
+
|
|
466
|
+
## 许可
|
|
467
|
+
|
|
468
|
+
[MIT](LICENSE)
|