qiyu-cli 0.2.0 → 0.2.2
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/README.md +349 -57
- package/dist/cli.js +48 -7
- package/dist/commands/api-notes.js +54 -0
- package/dist/commands/api.js +113 -39
- package/dist/commands/auth.js +150 -28
- package/dist/commands/credentials-source.js +30 -5
- package/dist/commands/db-notes.js +75 -0
- package/dist/commands/db.js +112 -113
- package/dist/commands/query-notes.js +58 -0
- package/dist/commands/query.js +427 -56
- package/dist/commands/skill.js +477 -38
- package/dist/commands/spec-types.js +101 -1
- package/dist/commands/stats.js +139 -30
- package/dist/commands/store-flags.js +18 -0
- package/dist/commands/store-notes.js +38 -0
- package/dist/commands/store-precheck.js +254 -0
- package/dist/commands/store.js +128 -75
- package/dist/commands/sync-notes.js +367 -0
- package/dist/commands/sync-run.js +155 -44
- package/dist/commands/sync.js +182 -121
- package/dist/core/config.js +274 -24
- package/dist/core/credentials.js +38 -4
- package/dist/core/edition.js +13 -3
- package/dist/core/envelope.js +73 -9
- package/dist/core/errors.js +73 -16
- package/dist/core/http.js +151 -52
- package/dist/core/ratelimit.js +5 -1
- package/dist/core/registry/index.js +26 -2
- package/dist/core/registry/params/export.session.check.json +17 -2
- package/dist/core/registry/params/export.session.json +24 -2
- package/dist/core/registry/params/export.session.one.json +10 -2
- package/dist/core/registry/params/export.session.one.message.json +17 -2
- package/dist/core/registry/specs.json +64 -42
- package/dist/core/shell.js +30 -0
- package/dist/core/time.js +1 -1
- package/dist/core/validate.js +21 -2
- package/dist/output.js +204 -28
- package/dist/postinstall.js +14 -5
- package/dist/query/errors.js +145 -45
- package/dist/query/mask.js +1277 -25
- package/dist/query/metric-catalog.js +11 -0
- package/dist/query/native-error.js +189 -0
- package/dist/query/sandbox.js +129 -24
- package/dist/query/table-query.js +36 -5
- package/dist/schedule/install.js +136 -13
- package/dist/skill/check.js +11 -6
- package/dist/skill/detect.js +122 -27
- package/dist/skill/install.js +233 -43
- package/dist/skill/paths.js +54 -0
- package/dist/skill/qiyu/SKILL.md +38 -8
- package/dist/skill/qiyu/errors.md +5 -4
- package/dist/skill/qiyu/protocols.md +57 -5
- package/dist/skill/qiyu/setup.md +6 -2
- package/dist/store/config.js +92 -16
- package/dist/store/duckdb.js +51 -5
- package/dist/store/retry.js +92 -4
- package/dist/store/schema.js +26 -3
- package/dist/sync/engine.js +257 -65
- package/dist/sync/registry.js +4 -0
- package/dist/sync/state.js +20 -0
- package/dist/sync/tasks/dim.js +23 -14
- package/dist/sync/tasks/knowledge.js +50 -8
- package/dist/sync/tasks/pipeline.js +29 -9
- package/dist/sync/tasks/reports.js +176 -49
- package/dist/sync/tasks/sessions.js +88 -21
- package/dist/sync/tasks/tickets.js +59 -8
- package/dist/sync/types.js +60 -1
- package/dist/sync/windowing.js +0 -22
- package/dist/sync/write-contract.js +47 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -6,8 +6,7 @@
|
|
|
6
6
|
JSON、用退出码表达该做什么、错误按语义分类、危险操作有硬门禁。有了它,Agent 不必先学会
|
|
7
7
|
七鱼 API 的 26 种响应信封、3 种分页和一堆静默失败,就能正确调用。
|
|
8
8
|
|
|
9
|
-
>
|
|
10
|
-
> 本地数据仓库的**同步**(`qiyu sync`)与**查询**(`qiyu db` / `qiyu query` / `qiyu stats`)均已交付,见[当前状态](#当前状态)。
|
|
9
|
+
> **状态**:设计稿中的**前六个子项目已交付**——认证与通用 API 通道、API 参数校验、存储层、同步引擎、查询接口与只读沙箱、Skill 化(见[当前状态](#当前状态))。
|
|
11
10
|
|
|
12
11
|
## 为什么需要它
|
|
13
12
|
|
|
@@ -63,13 +62,21 @@ npm 无法确认可信版本、也就无法 pin 版本,`--allow-scripts` 同
|
|
|
63
62
|
所以**不要指望 postinstall:直接运行 `qiyu skill install`**。
|
|
64
63
|
|
|
65
64
|
安装是幂等的:正文一致时不动正文(清单缺失或损坏时会补写 `.qiyu-skill.json`);要覆盖
|
|
66
|
-
你改过的正文得加 `--force
|
|
67
|
-
|
|
68
|
-
|
|
65
|
+
你改过的正文得加 `--force`。⚠️ 清单路径若被非普通文件(符号链接/目录)占用,清单本身写不
|
|
66
|
+
进去:裸 install 与 `--force` 都不改它;正文被改过时 `--force` 仍会覆盖正文(状态 `updated`)
|
|
67
|
+
但提示不会消失——先清理该占用再跑。其他子命令:
|
|
68
|
+
`qiyu skill where` 报告实体目录与各 Agent 的链接状态(只读,不修复),并给出**已安装那份
|
|
69
|
+
正文**的契约号与兼容判定(`data.entity.installed.compatible`,与 `data.cli_contract_version`
|
|
70
|
+
比较;判定不了时为 `null`,不是 `false`——实体不可用、清单缺失/损坏,以及正文被手工改过
|
|
71
|
+
(与清单记录的 `content_hash` 不一致)都属于判定不了);`qiyu skill check` 校验 skill 正文引用的命令、flag、位置参数取值与错误 `kind` 是否合 CLI 契约,
|
|
72
|
+
并把正文里**出现表名/完整 SQL 序列**判为违规(表名是「写了就红」,不是「校验它是否还存在」;
|
|
73
|
+
有违规退出码 1,CI 可跑;`--compare` 模式下
|
|
69
74
|
两份正文内容不一致、或已安装那份不可用,同样退 1)。
|
|
70
75
|
|
|
71
76
|
> 兜底提示:若 skill 未安装或已过期,`qiyu` 每次成功输出都会在 `meta.warnings` 里提醒
|
|
72
|
-
> 「未安装 / 已过期」——提示只写进 JSON
|
|
77
|
+
> 「未安装 / 已过期」——提示只写进 JSON,不改退出码。提示里给的是**能收敛的动词**:
|
|
78
|
+
> 清单缺失/损坏时同时给出 `qiyu skill install`(正文一致时收敛)与 `--force`
|
|
79
|
+
> (正文被手工改过时收敛),因为清单没了就判不出正文是否漂移。
|
|
73
80
|
|
|
74
81
|
## 配置凭证
|
|
75
82
|
|
|
@@ -80,14 +87,17 @@ export QIYU_APP_KEY=你的AppKey
|
|
|
80
87
|
export QIYU_APP_SECRET=你的AppSecret
|
|
81
88
|
```
|
|
82
89
|
|
|
83
|
-
|
|
90
|
+
在七鱼管理后台里能查看/生成 `appKey` 与 `appSecret` 的那一页可以找到这一对密钥
|
|
91
|
+
(不同版本后台的入口位置不同,仓库里记录过两种写法:`设置 → 开放平台` 与
|
|
92
|
+
`系统 → 扩展与集成 → 开发者 ID`;`appSecret` 首次需要点「重置」才显示——以你后台里
|
|
93
|
+
真实出现的那一页为准)。检查是否已配置:
|
|
84
94
|
|
|
85
95
|
```bash
|
|
86
96
|
qiyu auth whoami
|
|
87
97
|
# {"ok":true,"data":{"configured":true,"source":"env","profile":"default","robots":[]}}
|
|
88
98
|
```
|
|
89
99
|
|
|
90
|
-
|
|
100
|
+
也可以把凭证**写进配置文件**;之后除非用 `--profile` 指定了非 default 档,否则不必每次 export:
|
|
91
101
|
|
|
92
102
|
```bash
|
|
93
103
|
export QIYU_APP_KEY=... QIYU_APP_SECRET=...
|
|
@@ -95,8 +105,17 @@ qiyu auth login # 写入 default profile
|
|
|
95
105
|
qiyu auth login --profile staging # 写入指定 profile
|
|
96
106
|
```
|
|
97
107
|
|
|
108
|
+
⚠️ `--profile staging` **只写该档,不改顶层的 `defaultProfile`**:写完之后不带 `--profile`
|
|
109
|
+
的命令仍然按原顺序选档(`QIYU_PROFILE` > `defaultProfile` > 内置 `default`)。想固定用这一档,
|
|
110
|
+
按命令能力二选一:
|
|
111
|
+
- **接受 `--profile` 的命令**(`store *`、`db *`、`query`、`stats fields`、`sync run|status|verify|install`)
|
|
112
|
+
—— 在每条命令上写 `--profile staging`(`sync uninstall` 不接受它,见下一条);
|
|
113
|
+
- **不接受 `--profile` 的命令**(`api *`、`auth whoami`、`sync tasks`、`skill *`)—— 只能用
|
|
114
|
+
`export QIYU_PROFILE=staging`,或把配置顶层的 `defaultProfile` 改成 `staging`。
|
|
115
|
+
|
|
98
116
|
`auth login` 只从**环境变量**读凭证——不接受 `--app-key`/`--app-secret`(命令行参数会留在
|
|
99
|
-
shell 历史与 `ps` 输出里)。它把配置写到 `~/.config/qiyu/config.json
|
|
117
|
+
shell 历史与 `ps` 输出里)。它把配置写到 `~/.config/qiyu/config.json`(**新建**的目录 `0700`、文件 `0600`;
|
|
118
|
+
已存在的目录不会被改动——`0755` 是常规 umask 产物,含凭证时的门禁是「文件 `0600` + 目录不可 group/other 写」,见下方「权限规则」),
|
|
100
119
|
合并保留该 profile 下已有的 `store`/`robots` 键,且**绝不回显**凭证(连末四位都不)。
|
|
101
120
|
配置文件是符号链接时拒绝写入(防止穿透到任意路径)。
|
|
102
121
|
|
|
@@ -104,18 +123,84 @@ shell 历史与 `ps` 输出里)。它把配置写到 `~/.config/qiyu/config.js
|
|
|
104
123
|
此时 `auth whoami` 的 `source` 报 `mixed`。
|
|
105
124
|
|
|
106
125
|
存储配置仍是**手工编辑** `~/.config/qiyu/config.json`;也可用 `--db`/`QIYU_DB_PATH` 直接指定库路径。
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
126
|
+
⚠️ 空串口径与 profile 一致:`QIYU_DB_PATH=` / `QIYU_STORE_BACKEND=`(`export X=`,即"变量没填")
|
|
127
|
+
视为**未设置**,照常回落到配置文件里的 `profiles.<name>.store.path` / `profiles.<name>.store.backend`;
|
|
128
|
+
而**显式** `--db ''` / `--backend ''` 是用法错误——把明确给出的空值悄悄换成另一份资源不是回落,是静默改道。
|
|
129
|
+
空白串(`--db ' '`)不是空串,两者都拒绝,且报错点名**真正给了空白值的那一层**
|
|
130
|
+
(旧文案把三个来源一起指控为「均为空」,明明配了值的 `profiles.<name>.store.path` 也在其列)。
|
|
131
|
+
|
|
132
|
+
配置文件的完整结构(**顶层 / profile / store 三层的键名写错会被拒绝,退出码 2**):
|
|
133
|
+
|
|
134
|
+
```json
|
|
135
|
+
{
|
|
136
|
+
"defaultProfile": "default",
|
|
137
|
+
"profiles": {
|
|
138
|
+
"default": {
|
|
139
|
+
"store": {
|
|
140
|
+
"path": "~/.qiyu/duckdb/qiyu.duckdb",
|
|
141
|
+
"backend": "duckdb",
|
|
142
|
+
"readOnlyRetryMs": 30000,
|
|
143
|
+
"batchSize": 1000,
|
|
144
|
+
"options": { "knowledgeRobotIds": [1000001] }
|
|
145
|
+
},
|
|
146
|
+
"credentials": { "appKey": "…", "appSecret": "…" },
|
|
147
|
+
"robots": { "1000001": "机器人A" }
|
|
148
|
+
}
|
|
149
|
+
}
|
|
150
|
+
}
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
- 顶层只认 `defaultProfile` 与 `profiles`;profile 内只认 `store`/`credentials`/`robots`;
|
|
154
|
+
`store` 内只认上面那五个键。**没有 `store` 这一层之外的简写** —— 例如
|
|
155
|
+
`knowledgeRobotIds` 必须在 `profiles.<name>.store.options` 里,放到 `profiles.<name>` 下会被拒绝。
|
|
156
|
+
- ⚠️ `profiles.<name>.store.options` 的内层键**不做未知键校验**(内容由消费方解释):在它里面把
|
|
157
|
+
`knowledgeRobotIds` 拼成 `knowledgeRobotId` 不会被拒绝,只会静默不生效。改这一块时请对照
|
|
158
|
+
上面的示例逐字核对。
|
|
159
|
+
- `credentials` 由 `qiyu auth login` 写入(也可手写);**`store` 与 `robots` 只能手写** ——
|
|
160
|
+
`auth login` 会保留已有的 `robots` 映射,但不会创建或更新它。
|
|
161
|
+
- **profile 的选择顺序**:`--profile` > `QIYU_PROFILE` > 顶层 `defaultProfile` > 内置 `default`。
|
|
162
|
+
点名的 profile **必须存在于 `profiles` 里**:`--profile prodd`(拼错)或 `defaultProfile`
|
|
163
|
+
指向不存在的名字会被拒绝(退出码 2,错误里列出已有的 profile),**不会静默回落到默认库**。
|
|
164
|
+
刻意保留的回落只有四种:配置文件不存在(首次运行)、`profiles` 为空、profile 存在但没写
|
|
165
|
+
`store` 块(用内置默认路径)、未点名任何 profile 时直接用内置 `default`(它不在
|
|
166
|
+
`profiles` 里也不报错)。空串口径:`--profile ''` 是 usage 错误;`QIYU_PROFILE=` 与
|
|
167
|
+
`"defaultProfile": ""` 视为未设置。
|
|
168
|
+
|
|
169
|
+
**权限规则**:配置文件**含凭证**且 group/other 有**任何**权限位(如 `0644` 可读、`0622` 只写、
|
|
170
|
+
`0601` 仅 other 可执行)时,**任何读取配置的命令都会拒绝读取**(`kind: config_insecure`,
|
|
171
|
+
退出码 1,hint 点名要执行的 `chmod`)——可读时落盘的 appSecret 对同机其他用户可读,
|
|
172
|
+
其余组合也不该放宽,判据就是 `mode & 0o077 !== 0`。文件**读不出来**(权限拒绝,
|
|
173
|
+
`EACCES`/`EPERM`)同样按 `config_insecure` 报(退出码 1 + `chmod 600` hint)——它是权限
|
|
174
|
+
问题,不是配置内容问题;而**配置目录**不可搜索(目录进不去、连文件都 stat 不到)报的是
|
|
175
|
+
另一句话,hint 是 `chmod 700 <目录>`——对文件 chmod 在这个状态下本身就执行不了,不会把
|
|
176
|
+
「目录挡路」说成「凭证缺失」。不读配置的命令(`--version`、
|
|
177
|
+
`api list`、`skill where`、`sync tasks` 等)不受影响,它们不碰凭证。不含凭证的文件维持
|
|
178
|
+
「只在 stderr 警告、不阻断」。
|
|
179
|
+
父目录 group/other **可写**(文件可被整体替换)时同样拒绝。`auth login` 是**唯一的例外**:
|
|
180
|
+
它不拒绝,而是把已有文件重写为 `0600`(马上要写入新的 secret,拒绝没有意义),写完自检
|
|
181
|
+
不合格才报 `config_insecure`。Windows 上跳过这些检查(「过宽」判据只看 POSIX 权限位);
|
|
182
|
+
但**读被拒绝**(NTFS ACL)在 Windows 上同样会按 `config_insecure` 报,此时 hint 是
|
|
183
|
+
`icacls <路径> /reset`(恢复继承的 ACL)—— `chmod` 不存在于 Windows,POSIX 修法照搬过去
|
|
184
|
+
用户将无路可走。数据库正常关闭后 `.wal` 临时文件会
|
|
185
|
+
自动消失,请勿手工删除。
|
|
112
186
|
|
|
113
187
|
> ⚠️ `whoami` **只检查凭证是否存在**,不校验它是否有效——一个拼错的 AppKey 同样返回
|
|
114
188
|
> `configured: true`。第一次真实调用才是唯一的验证。
|
|
115
189
|
>
|
|
190
|
+
> `whoami` 输出的 `profile` 是**本次解析出的档名**(顺序同上:`QIYU_PROFILE` > `defaultProfile` >
|
|
191
|
+
> 内置 `default`,空串一律视为未设置)。⚠️ 它**不保证该档在配置文件里存在**:环境变量给了一个
|
|
192
|
+
> 配置文件里没有的名字(拼错)时,`whoami` 照样按 env 凭证报 `configured: true`;而只要配置文件里
|
|
193
|
+
> **已有其它档**,`store` / `db` / `sync` / `query` 对同一个名字会以退出码 2 拒绝(它们要读该档的
|
|
194
|
+
> `store` 块)—— 这几条命令才是「档名拼错」的权威判据(配置文件 `profiles` 为空时它们按内置
|
|
195
|
+
> 默认路径照常工作,不报错)。
|
|
196
|
+
>
|
|
116
197
|
> `whoami` 输出的 `robots` 来自配置里的 `profiles.<name>.robots`(`{"1000001":"机器人A"}` 形态),
|
|
117
|
-
> 同样**未校验有效性**。它是 `sync run` 的兜底来源:`store.options.knowledgeRobotIds`
|
|
118
|
-
>
|
|
198
|
+
> 同样**未校验有效性**。它是 `sync run` 的兜底来源:`profiles.<name>.store.options.knowledgeRobotIds`
|
|
199
|
+
> 缺席时,知识库类目同步会用这些 id 驱动(`knowledgeRobotIds` 优先)。空数组有**三种**成因:
|
|
200
|
+
> 该档没配 robots、该档根本不存在,或**配置文件读取失败**(畸形 JSON / 未知键)——
|
|
201
|
+
> 第三种会在 `meta.warnings` 里点名,先读 `warnings` 再判断,别把读不到配置当成「该档没配」。
|
|
202
|
+
> (含凭证且权限过宽、或文件因权限**不可读**,都不是「读取失败」:那两种情况 `whoami`
|
|
203
|
+
> 直接以 `config_insecure` 报错,不进 warnings。)
|
|
119
204
|
|
|
120
205
|
## 使用
|
|
121
206
|
|
|
@@ -165,7 +250,8 @@ qiyu skill install [--dir <path>] [--link <agent>]... [--no-link] [--force] [--d
|
|
|
165
250
|
qiyu skill check [--installed [--dir <path>] | --compare [--dir <path>]]
|
|
166
251
|
校验 skill 引用的命令/表/错误 kind(有违规退出码 1;
|
|
167
252
|
--compare 下内容不一致也算失败)
|
|
168
|
-
qiyu skill where [--dir <path>] 报告实体目录与各 Agent
|
|
253
|
+
qiyu skill where [--dir <path>] 报告实体目录与各 Agent 链接状态(只读,不修复),
|
|
254
|
+
并报已安装正文的契约号与 compatible 判定
|
|
169
255
|
qiyu --version 包版本 + skill_contract_version
|
|
170
256
|
```
|
|
171
257
|
|
|
@@ -176,11 +262,14 @@ qiyu --version 包版本 + skill_contract_version
|
|
|
176
262
|
### 成功
|
|
177
263
|
|
|
178
264
|
```json
|
|
179
|
-
{"ok":true,"data"
|
|
265
|
+
{"ok":true,"data":<接口载荷>}
|
|
180
266
|
```
|
|
181
267
|
|
|
182
|
-
|
|
183
|
-
"接口无载荷"与"我解析错了"
|
|
268
|
+
`ok` 与 `data` 两个键恒在:`data` 即使为空也写成 `null`(不会整个消失),这样 Agent 能区分
|
|
269
|
+
"接口无载荷"与"我解析错了"。`meta` 是**条件键**:没有元数据时不出现。当前每条成功命令
|
|
270
|
+
都至少带 `meta`(多为 `field_notes`,`api call` 至少带 `endpoint`),但**读 `meta` 前仍要
|
|
271
|
+
先判存在** —— 键不出现 = 没有这项信息(与下方失败信封的可选键同一纪律),不是 `null`、
|
|
272
|
+
更不是解析失败。
|
|
184
273
|
|
|
185
274
|
### 失败
|
|
186
275
|
|
|
@@ -190,13 +279,17 @@ qiyu --version 包版本 + skill_contract_version
|
|
|
190
279
|
|
|
191
280
|
**请按 `kind` 分支,不要按 `code`。** `code` 只是个标签:它可能是服务端的数字码
|
|
192
281
|
(如 `14009`),也可能是本 CLI 合成的词(`usage` / `network` / `internal` /
|
|
193
|
-
`auth_missing` / `
|
|
194
|
-
`
|
|
195
|
-
|
|
282
|
+
`auth_missing` / `config_insecure` / `config_invalid` / `confirm_required` / `store_locked` /
|
|
283
|
+
`store_not_initialized` / `local_rate_limit` / `query_error` / `sandbox_blocked` /
|
|
284
|
+
`query_timeout` / `sync_not_run` / `unknown`)。合成词在官方错误码表里查不到。
|
|
285
|
+
⚠️ 上面与 `qiyu --help` 里的是一批**常见值**,不是穷举:`kind` 的单一事实源是
|
|
286
|
+
`src/core/errors.ts` 的 `ERROR_KINDS`,逐条的成因与动作表见 skill 文档 `errors.md`
|
|
287
|
+
(`qiyu skill install` 后随正文提供)。
|
|
196
288
|
|
|
197
289
|
错误信封还可能有这几个**可选**键(缺省即不出现该键):
|
|
198
290
|
|
|
199
|
-
- `retry_after: {seconds, source}` —— 建议等待秒数与它的来源(`
|
|
291
|
+
- `retry_after: {seconds, source}` —— 建议等待秒数与它的来源(`header` = 服务端
|
|
292
|
+
`Retry-After` 响应头直接指定,最可信、优先于其余来源 / `observed` 实测 /
|
|
200
293
|
`doc` 文档值 / `local` 本地令牌桶 / `fallback` 保守兜底)
|
|
201
294
|
- `retry_strategy` + `fallback` —— **只在 `api call` 撞限流、且该接口非危险操作、
|
|
202
295
|
有对应本地表、本地库文件存在时出现**:`"switch_to_local"` + 一条
|
|
@@ -225,28 +318,93 @@ qiyu --version 包版本 + skill_contract_version
|
|
|
225
318
|
### store 命令的输出
|
|
226
319
|
|
|
227
320
|
`store init` 与 `store status` 成功时输出六字段:`path` / `backend` / `config_path` /
|
|
228
|
-
`config_exists` / `schema_version` / `tables
|
|
229
|
-
|
|
230
|
-
|
|
321
|
+
`config_exists` / `schema_version` / `tables`,外加 `meta.field_notes`(逐键释义)。
|
|
322
|
+
其中 `tables` 是表清单,但**形状随命令不同**:`store status` 给 `[{name, rows}]`(行数是
|
|
323
|
+
真实 `COUNT(*)`),`store init` 给表名数组 `["a","b"]`。
|
|
324
|
+
⚠️ 另外两点容易误读:`tables` 只列**本 CLI 声明的表**(`TABLES`,与 `db tables` 同一组、
|
|
325
|
+
含内部表 `schema_version` / `sync_state` / `sync_gaps`,所以两边数量应当一致);库里
|
|
326
|
+
有而本 CLI **未声明**的表(旧版 CLI 或其它工具建的)不出现在 `tables` 里,而是在
|
|
327
|
+
`meta.warnings` 中点名 —— 数量不等时先读 `warnings` 判成因,不要径直断定「有表缺失」。
|
|
328
|
+
`schema_version` 要跟当前 CLI 的版本(`LATEST_VERSION`)比才有意义,小于它就是
|
|
329
|
+
旧版 CLI 建的库,`store init` 只补建缺失的迁移、不重放已应用的。`store status` 的每次调用都要对
|
|
330
|
+
各表做全表 `COUNT`(行数无缓存),轮询代价与数据量成正比,Agent 不应把它当作高频健康
|
|
331
|
+
检查来用。
|
|
231
332
|
|
|
232
333
|
### sync 命令的输出
|
|
233
334
|
|
|
234
335
|
`sync run` 的 stdout 是 `{tasks:[...], truncated:false}`,每个任务含 `task` / `status`
|
|
235
|
-
(complete/partial/failed)/ `windows`(`{total, succeeded, failed, skipped}`,
|
|
236
|
-
`total = succeeded + failed + skipped`,`skipped`
|
|
336
|
+
(complete/partial/failed)/ `windows`(`{total, succeeded, failed, skipped, contained?}`,
|
|
337
|
+
`total = succeeded + failed + skipped`,`skipped` 有三种成因:跳过的**残段窗**数 +
|
|
338
|
+
**整窗晚于末端上限被丢弃**的窗数 + **覆盖窗失败**时其名下被合并、该拉没拉的窗数;
|
|
339
|
+
`contained` 仅在 > 0 时出现 = 完全落进前一窗**回看重叠区**、被合并的
|
|
340
|
+
窗数(overlapDays > 0 的任务;**覆盖窗成功**时数据已由那一窗覆盖,所以不算 skipped、也不计入
|
|
341
|
+
total —— 覆盖窗失败时这些窗改记 skipped 并逐窗出进度行;物理切出的窗数 = total + contained),
|
|
342
|
+
见下)/ `rows` /
|
|
237
343
|
`resolved_range`(Asia/Shanghai 的 `+08:00` ISO 二元组)/ `watermark` / `last_synced_at` /
|
|
238
344
|
`gaps` / `notes`。`gaps[].range` 与 `resolved_range` 同形态(同一套时间解析);
|
|
239
|
-
`notes`
|
|
240
|
-
|
|
345
|
+
`notes` 是中文说明数组(恒在,常为空),**有意跳过而非故障**——看到它不代表本轮失败。
|
|
346
|
+
来源一:「请求区间早于接口可得数据的最早边界」(把「区间不可得」与「同步故障」分开);
|
|
347
|
+
来源二:日对齐任务遇到非上海日界的 `--until`,两档——该日不早于末端上限(调整 `--until`
|
|
348
|
+
无用,要等上限自然前移再跑增量)或末窗是半个自然日按残段窗跳过(该日未同步,要含该日
|
|
349
|
+
请把 `--until` 写到次日 0 点)。末段有无被跳过看 `windows.skipped`,不要只凭本数组为空判断。
|
|
350
|
+
|
|
351
|
+
⚠️ **`watermark` / `last_synced_at` 是 UTC `Z` 形态**(引擎写库的原样字符串),与同一行里
|
|
352
|
+
`resolved_range` 的 `+08:00` 形态**写法不同**——两者可以是同一时刻
|
|
353
|
+
(实测 `"…08:53:20.000Z"` 与 `"…16:53:20+08:00"` 是同一瞬间)。直接按字符串比较会得出
|
|
354
|
+
相反结论,先解析成时刻再比。`watermark` 是「数据覆盖到哪」,`last_synced_at` 是
|
|
355
|
+
「那次提交发生在什么时候」——⚠️ **它按成功窗更新、不按轮**:一轮里有部分窗口失败
|
|
356
|
+
(`sync run` 报 `partial`)时它照样被更新(实测:中窗失败 → `partial` 而它已是末个成功窗
|
|
357
|
+
的提交时刻);它也**可能晚于水位实际前进的时刻**(断链后的成功窗仍刷新它,水位却冻结在
|
|
358
|
+
连续成功末端,实测同一轮里两者相差数分钟)。只有整轮没有任何带水位写入的成功提交
|
|
359
|
+
(首窗即失败 / 全窗失败 / 快照失败 / 窗口全是被跳过的残段窗)才保留上一轮的值。
|
|
360
|
+
`sync status` 的这两个字段形态相同,但它的 `gaps[].range` 与 run 不同(epoch 毫秒原样,
|
|
361
|
+
见下)。
|
|
241
362
|
|
|
242
363
|
**`ok` 与退出码的双轨语义**:`ok:true` 表示「命令已产出结果」,**退出码才是成败的权威
|
|
243
|
-
|
|
244
|
-
`
|
|
364
|
+
判据**。以下五种情况 stdout 都是 `{ok:true,data:…}`(**没有** `error` 对象)而退出码为 1
|
|
365
|
+
——「结果里有问题」就是它要报告的内容:`sync run` 全窗失败(`status:partial` 且
|
|
366
|
+
`windows.succeeded = 0`)、`sync verify` 的 `drift` 非空、`sync install` / `sync uninstall
|
|
367
|
+
--yes` 有命令执行失败、`skill check` 有违规、`skill check --compare` 两侧不一致。
|
|
368
|
+
请先看退出码,再看 `data`;不要因为它们退出码 1 就去读 `error.kind`。
|
|
369
|
+
|
|
370
|
+
**`tasks[].status` 的三个取值**(`sync run`;逐值动作见输出的 `meta.field_notes`):
|
|
371
|
+
|
|
372
|
+
| status | 含义 | 该做什么 |
|
|
373
|
+
|---|---|---|
|
|
374
|
+
| `complete` | **没有失败窗口**(`windows.failed = 0`) | 正常 —— ⚠️ 但不保证「全部窗口都跑了」:`windows.skipped` 可能大于 0(**残段窗**或**整窗晚于末端上限**两种;覆盖窗失败转 skipped 那种必然带 `windows.failed > 0`,只会出现在 `partial`),判实际覆盖要看 `windows.skipped` |
|
|
375
|
+
| `partial` | 至少一个窗口失败 | ⚠️ **它也覆盖「一行都没落」**:全窗失败时 `windows.succeeded = 0` 但 status 仍是 `partial`(退出码 1)。两个字段分开读:`windows.succeeded` 是成功窗数(**空窗也算成功**,大于 0 不代表有行);`rows.written` 是写入行数(为 0 也可能是「窗口都成功、只是上游没数据」;⚠️ count_mismatch / write_failed 的失败窗记的是「参与核对的应写行数」——那批行已回滚、实际没落库,这两类失败窗存在时它**偏大**) |
|
|
376
|
+
| `failed` | 快照任务的失败(本地限频闸门拦截 / 上游取数失败 / 落库失败或行数核对不符) | 快照没有窗口循环,所以不会出现 `partial`;反过来 windowed 任务也**不会**给出 `failed` —— 全窗失败同样是 `partial` |
|
|
377
|
+
|
|
378
|
+
`sync status` 的 `data` 是 `{tasks:[…]}`(图例键即该路径下的字段,如 `tasks[].range_status`),
|
|
379
|
+
每任务输出 `{task, watermark, range_status, last_synced_at, resolved_range,
|
|
380
|
+
gaps, gaps_count, locked}`:`resolved_range` 是上次成功推进的水位区间(形态同 run 的
|
|
381
|
+
`resolved_range`,但 ⚠️ `start` 是**水位起点语义**、含可能被跳过的首残段前缀 ——
|
|
382
|
+
本命令不输出 `windows.skipped`,判实际覆盖要看 `sync run` 的 `windows.skipped`),
|
|
383
|
+
`gaps` 是历史缺口逐条 `{range, reason, detail, recorded_at}`。
|
|
245
384
|
|
|
246
|
-
`
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
385
|
+
**`range_status` 的取值**(逐值动作见 `meta.field_notes`)——⚠️ **两个取值的字面都与
|
|
386
|
+
事实不符,别按字面用**(2026-10-27 实测):
|
|
387
|
+
|
|
388
|
+
| range_status | 真实含义 | 常见误读 |
|
|
389
|
+
|---|---|---|
|
|
390
|
+
| `complete` | **水位推进过**(引擎每个成功窗都写它) | ❌ 不是「全窗口成功」:3 窗中窗失败 → run 报 `partial` 而这里仍是 `complete`。判数据完整要综合三个判据:**覆盖范围**(`resolved_range`,以及 `sync run` 的 `windows.skipped` —— 本命令不输出它)、**历史缺口新鲜度**(按 `range` 对照,见下)、**空 `gaps` 不等于完整**(`skipped > 0` 时可能 `gaps` 为空但仍有未覆盖段) |
|
|
391
|
+
| `pending` | **最近一次运行没推进水位**(每轮开跑就置 pending,成功窗才推回 complete) | 三种误读都要避免:❌ 不是「库里没数据」(首窗失败时后续成功窗照常落库、只是不推水位,实测 pending 且表里有 2 行);❌ 不是「从未同步过」(先成功一轮、再跑一轮首窗失败同样回到 pending,而 `watermark` 保留上一轮的值);❌ 也不是「正在同步」(并发写者会让本命令退避等待,等到后读到的是那一轮的结果) |
|
|
392
|
+
| `null` | 该任务在 `sync_state` 里**没有行** | ❌ 不是「同步失败」:从未跑过,或只跑过被跳过的残段窗 |
|
|
393
|
+
|
|
394
|
+
`locked:true` 表示 `sync_state` 里有**残留**的写者章(上一轮运行被强杀)——它同样是
|
|
395
|
+
「不是正在同步中」:真正持锁的进程会让本命令退避等待(`readOnlyRetryMs`,默认 30 秒),
|
|
396
|
+
等到说明那一轮已结束(返回 `false`),等不到才报 `store_locked`。看到 `true` 说明写锁
|
|
397
|
+
当前是空的、章是残留的,重跑 `sync run` 即可。
|
|
398
|
+
|
|
399
|
+
`gaps` 是 `sync_gaps` 里的**历史**缺口,含已不再适用的旧记录(成功窗只清它自己那个
|
|
400
|
+
起点的缺口;换了窗口边界重跑不会清掉旧起点的记录)——`gaps` 非空 ≠ 当前数据有问题。
|
|
401
|
+
⚠️ 旧记录与新记录的 `reason` **相同**,按 `reason` 区分不出新旧;`range` 也只能说明
|
|
402
|
+
「相关」——换边界重跑后数据可能已补齐,而旧缺口的 `range` 仍与你评估的区间重叠。
|
|
403
|
+
**没有一次覆盖核对就不能确认新鲜度**:报「该区间有历史缺口记录,新鲜度未确认」,
|
|
404
|
+
不要直接报成当前故障。⚠️ `gaps[].range` 是 epoch 毫秒字符串(原样回显存储值),与 `sync run` 的
|
|
405
|
+
`+08:00` ISO 形态**不同**,比较前先统一形态。
|
|
406
|
+
|
|
407
|
+
`sync verify` 输出 `{tasks:[…]}`,每任务 `{task, local_rows, expected_from_api, state_windows_consistent, drift}`:
|
|
250
408
|
**`expected_from_api` 只对快照任务有意义**(上游 fetch 的行数);windowed 任务不做上游
|
|
251
409
|
全量重拉,该字段恒为 `null`,核对方式是「本地行数 ↔ sync_state 成功状态」的一致性
|
|
252
410
|
(`state_windows_consistent`)——两种任务的核对方式不同,读 drift 前先看任务 kind。
|
|
@@ -254,6 +412,45 @@ gaps, gaps_count, locked}`:`resolved_range` 是上次成功推进覆盖的区
|
|
|
254
412
|
`payload` 列在列内,它是整行 PII 的完整副本,不要 `SELECT *`)。本阶段**没有**任务的
|
|
255
413
|
启用/停用机制:注册表里的任务总是全部执行(选定任务靠命令行显式列出)。
|
|
256
414
|
|
|
415
|
+
**`gaps[].reason` 的全部取值**(Agent 按值分支;`sync run` 的 `gaps` 条目不含
|
|
416
|
+
`recorded_at`,是本轮即时产出):
|
|
417
|
+
|
|
418
|
+
| reason | 含义 | 该做什么 |
|
|
419
|
+
|---|---|---|
|
|
420
|
+
| `rate_limit_local` | 本地限频冷却未到点(持久化冷却,跨进程有效) | 等到 `detail` 里的时刻再重跑覆盖该区间;提前重跑必然再失败 |
|
|
421
|
+
| `fetch_failed` | 取数失败(有界重试后仍失败,本窗未写入) | 稍后重跑覆盖该区间 |
|
|
422
|
+
| `write_failed` | 落库失败(事务已回滚,本窗未写入) | 检查本地库(锁/磁盘)后重跑 |
|
|
423
|
+
| `count_mismatch` | 写入意图行数 ≠ API 声明行数(事务已回滚) | 重跑;持续不符报告人类 |
|
|
424
|
+
| `knowledge_row_malformed` | 快照映射时缺键列的行被丢弃(响应形态漂移);含知识库类目树里缺 id 的节点(连同其子树) | 报告人类核对接口形态;快照全删重插下这些行已消失 |
|
|
425
|
+
| `staff_id_list_malformed` | 分两种:`staffIdList` 非数组 → **该组全部成员**未落库(整组跳过);成员 id 为空 → **该成员**未落库(同组其余成员照常落库) | 报告人类核对接口形态;快照全删重插下这些成员已消失 |
|
|
426
|
+
| `row_missing_key` | 窗口任务(报表 / 工单 / 工单日志)映射时行缺主键列(缺键或空串),**该行未落库**;`detail` 是丢弃行数(工单日志另点名「因缺 id 整单未拉取」的工单数) | 报告人类核对接口形态;`fetched`/`written` 都不含这些行,窗口仍可能 complete |
|
|
427
|
+
| `filter_matched_no_staff` | 报表筛选条件未命中任何客服(本窗按 0 行记) | 结合筛选条件判断——它不是「没有数据」的证据 |
|
|
428
|
+
| `export_fixture_unreported` | 导出流未上报窗口声明行,空窗可能真空也可能被截断 | 抽查该窗行数,必要时重跑 |
|
|
429
|
+
| `export_window_mismatch` | 导出声明的窗口宽于请求(重叠行由幂等 upsert 吸收) | 数据不受损,知悉即可 |
|
|
430
|
+
|
|
431
|
+
⚠️ 上表里 `rate_limit_local` / `fetch_failed` / `write_failed` / `count_mismatch` 是**失败缺口**
|
|
432
|
+
(该窗未写入);其余都是**成功窗上的提示**(窗口数据照常提交)—— `gaps` 非空不等于同步失败。
|
|
433
|
+
但「提示」**不等于「数据没缺」**,两档要分开读:
|
|
434
|
+
`knowledge_row_malformed` / `staff_id_list_malformed` / `row_missing_key` 描述的行**确实没落库**
|
|
435
|
+
(`detail` 是丢失规模,必须核对上游形态;⚠️ `staff_id_list_malformed` 的整组一档只给
|
|
436
|
+
**受影响的组数**与「成员数未知」—— 它不是行数,别当规模直接用);`filter_matched_no_staff` /
|
|
437
|
+
`export_fixture_unreported` / `export_window_mismatch` 则**未必缺数据**
|
|
438
|
+
(可能只是筛选没命中、或空窗本来就空,按 `detail` 判断)。
|
|
439
|
+
新增 reason 必须同时更新本表与源码枚举(`tests/sync-enums.test.ts` 双向核对)。
|
|
440
|
+
|
|
441
|
+
**`drift[].kind` 的全部取值**(`sync verify`):`not_synced`(从未同步 → 先 `sync run`)、
|
|
442
|
+
`state_pending`(上次运行未完成或中断 → 重跑 `sync run` 补全后再 verify)、
|
|
443
|
+
`count_mismatch`(本地行数 ≠ 上游行数,仅快照任务 → 重跑覆盖,持续不符报告人类)、
|
|
444
|
+
`fetch_failed`(上游取数失败,**无法核对 ≠ 一致** → 稍后重试 verify)。
|
|
445
|
+
|
|
446
|
+
⚠️ `sync verify` 的 `state_windows_consistent: true` **不等于「数据完整」**,`drift` 为空
|
|
447
|
+
或退出码 0 **同样不能当完整性证据**。对 **windowed 任务**,本命令只核对同步状态记录,而
|
|
448
|
+
`range_status=complete` 只说明水位推进过(见上表)——2026-10-27 实测:3 窗中窗失败的库,
|
|
449
|
+
`verify` 直接给出 `drift: []` + 退出码 0,而 `sync_gaps` 里那条 `fetch_failed` 仍在。
|
|
450
|
+
(快照任务另有上游行数核对,见上 `expected_from_api`。)windowed 的完整性要另行核对
|
|
451
|
+
两处:`sync status` 的 `gaps` 与 `resolved_range`(能否确认新鲜度见该段说明),以及
|
|
452
|
+
`sync run` 的 `windows.skipped`(本命令与 `sync status` 都不输出它)。
|
|
453
|
+
|
|
257
454
|
**聚合报表按天切片(窗口 1 天)**:九个报表接口返回的是**窗口聚合值**(`overview` 一行
|
|
258
455
|
全局汇总、`staffworklod` 每客服一行、`transferHuman` 恒 1 行),响应里的 `date` 原文是
|
|
259
456
|
"this date has no specific meaning, it only indicates the start time of the current query"
|
|
@@ -263,14 +460,21 @@ gaps, gaps_count, locked}`:`resolved_range` 是上次成功推进覆盖的区
|
|
|
263
460
|
`sync run --full` 对报表任务会从 1970 起切出**上万窗**(≈ 56 年 × 每天 1 窗,每窗至少
|
|
264
461
|
一次调用)——首跑与回补历史请用 `--since/--until` 限定区间(如 `--since 30d` = 30 窗/任务)。
|
|
265
462
|
|
|
266
|
-
**窗口端点按上海日界对齐**:8
|
|
267
|
-
上海自然日 0
|
|
463
|
+
**窗口端点按上海日界对齐**:8 张**声明了 `windowAlign: 'shanghaiDay'` 的报表表**(考勤除外)的窗口起点按
|
|
464
|
+
上海自然日 0 点对齐——其中 6 张的 `stat_date` 在主键里(`order_performance` 的主键是
|
|
465
|
+
`order_id`、`staff_salary_detail` 的是 `staff_id + work_date`),这 6 张才可按 `stat_date` 关联——水位续跑(`watermark+1ms`)或任意时刻
|
|
268
466
|
`--since` 产生的「错相位窗」(如 `[今天18:23, 明天18:23)`)只写一行 `stat_date` 却装着
|
|
269
467
|
跨两天聚合、还会把「明天」日的行删掉不重写。对齐后:**实际拉取的每窗恰是一个完整上海
|
|
270
468
|
自然日**,按日增量的「每日概览」日行恒为全天值。**显式区间的非日界首末段是残段窗**(如
|
|
271
469
|
`--since 30d` 的首段 `[起点, 次日0点)` 与末段 `[昨天0点, 终点)`、`--full` 起点钳出的
|
|
272
470
|
16 小时段)——引擎**跳过不落库**(半日聚合不写日行,避免覆盖该日的整日聚合值;
|
|
273
|
-
`windows.skipped` 如实计数、每窗一条 stderr
|
|
471
|
+
`windows.skipped` 如实计数、每窗一条 stderr 进度行)。**`skipped` 也计入「整窗晚于
|
|
472
|
+
末端上限被丢弃」的窗**(`windowEndClamp`,考勤/绩效请求到「今天」时):这类窗同样
|
|
473
|
+
不 fetch、不算成功,但会出现在 `skipped` 里并逐窗出「晚于末端上限」进度行。
|
|
474
|
+
**第三种成因:覆盖窗失败的合并窗**——overlapDays > 0 的任务里,被前一窗回看重叠区
|
|
475
|
+
合并的窗在覆盖窗成功时算 `contained`,覆盖窗失败时就是「该拉的没拉」,改记 `skipped`
|
|
476
|
+
并逐窗出「须重跑补齐」进度行;此时本轮 status 必为 `partial`,看 `gaps` 找到失败的覆盖窗。
|
|
477
|
+
`skipped > 0` 不等于「都是有意不拉的窗」,判实际覆盖先分清这三种成因。**末残段**的整日值**可能**由其
|
|
274
478
|
请求区间覆盖该整天的日对齐 run 补全(水位停在最后一个整日窗末端;若下一轮的请求区间
|
|
275
479
|
仍未覆盖该整天,该段仍是残段、继续跳过——不保证「下一次 run」就补上);
|
|
276
480
|
**首残段**不落日行也**不补**——该半日段没有合法落点(写入即半日覆盖整日),属显式
|
|
@@ -284,9 +488,21 @@ gaps, gaps_count, locked}`:`resolved_range` 是上次成功推进覆盖的区
|
|
|
284
488
|
**`sync install` 与调度环境**:调度条目不继承你的 shell 环境——launchd 的用户域不含
|
|
285
489
|
shell rc 变量。存储定位走环境变量(`QIYU_DB_PATH` 等)时,install 会把**解析出的绝对
|
|
286
490
|
路径/名称固化为调度命令的 `--db/--profile/--backend` 参数**(显式 flag 优先;只走配置
|
|
287
|
-
文件或默认值时不固化,调度任务自己读得到 HOME
|
|
491
|
+
文件或默认值时不固化,调度任务自己读得到 HOME 下的配置文件)。⚠️ 空串视为未设置
|
|
492
|
+
(`export QIYU_PROFILE=` 是"变量没填"的典型形态,不会被固化成 `--profile <空>`——
|
|
493
|
+
那会让每次调度执行都报「--profile 不能为空」)。`QIYU_DB_PATH=` / `QIYU_STORE_BACKEND=`
|
|
494
|
+
同理:**解析结果不固化**——否则等于把"当时读到的配置文件值"悄悄升级成一个显式 flag,
|
|
495
|
+
之后改配置文件对已装的调度任务永远不生效。若凭证走
|
|
288
496
|
`QIYU_APP_KEY`/`QIYU_APP_SECRET`,请确认其对该调度上下文可用——调度条目**不写入任何
|
|
289
497
|
凭证**(秘密进 plist/unit 文件是安全红线)。
|
|
498
|
+
⚠️ 上面说的是**环境变量**的空串。**显式 flag** 的空白取值是用法错误、不是「没给」:
|
|
499
|
+
`sync run --since ''` / `--until ''` 退出码 2(不传这个 flag 才是「不给区间」),
|
|
500
|
+
`sync install --schedule ''` 同样退出码 2,且消息把取值渲染成 `''` / `' '`
|
|
501
|
+
(否则冒号后一片空白,Agent 读不出自己传了什么)。`query --table … --since ''`
|
|
502
|
+
一直是这个口径,sync 侧 2026-10-29 对齐(此前 `--since ''` 被真值判据当成「没给」,
|
|
503
|
+
`--full --since ''` 还**绕过互斥守卫**跑了一次全量重刷)。`sync install` 的 cron
|
|
504
|
+
解析也排在存储前置探测**之前**:未同步过的库上 `--schedule '不是 cron'` 报参数错误,
|
|
505
|
+
而不是先让你「去跑一次同步」再报。
|
|
290
506
|
|
|
291
507
|
### 查询命令的输出
|
|
292
508
|
|
|
@@ -301,7 +517,9 @@ shell rc 变量。存储定位走环境变量(`QIYU_DB_PATH` 等)时,insta
|
|
|
301
517
|
`meta` 恒含:
|
|
302
518
|
`rows`(截断后的实际行数)/ `truncated`(是否被 `--limit` 截断)/ `limit_applied`(生效上限)/
|
|
303
519
|
`masked`(本次是否脱敏)/ `masked_columns`(**实际被改写**的列名,全 null 的列不算)/
|
|
304
|
-
`mask_warnings
|
|
520
|
+
`mask_warnings`(脱敏缺口与副作用警告)/ `resolved_range` / `data_coverage` / `warnings`。
|
|
521
|
+
**每个键的逐条释义与动作见输出的 `meta.field_notes`**(两个通道同一份,不必回头查本段);
|
|
522
|
+
下面几条是人读版的重点。
|
|
305
523
|
|
|
306
524
|
- `--table` 通道的输出顺序是**确定的**:无 `--group-by` 时,**有时间列的表**按时间列降序、
|
|
307
525
|
再按主键升序(`--limit` 截到的因此是**最新**的那些行);**无时间列的表**只能按主键升序。
|
|
@@ -310,8 +528,22 @@ shell rc 变量。存储定位走环境变量(`QIYU_DB_PATH` 等)时,insta
|
|
|
310
528
|
(`+08:00` ISO 二元组),不是原始输入——`iso-day` 表会向下取整到上海自然日,
|
|
311
529
|
所以要按它判断覆盖了哪几天。`--sql` 通道恒为 `null`(任意 SQL 无法通用判定)。
|
|
312
530
|
- `data_coverage`:该表时间列在**过滤范围内**的 MIN/MAX(`+08:00` ISO);`--sql` 通道恒为 `null`。
|
|
313
|
-
它有三种 `null`
|
|
314
|
-
|
|
531
|
+
它有三种 `null` 成因:`--sql` 通道 / 该表无时间列 / 范围内没有一行的时间值能过形态谓词
|
|
532
|
+
(空表、过滤后 0 行、时间列全是脏值或 NULL)。前两种能从通道与表定义直接看出,
|
|
533
|
+
第三种只能靠这条规则识别——时间列全是脏值时 `rows` 仍可能大于 0,没有时间过滤时这份响应里
|
|
534
|
+
不会有关于它的警告。有些表的时间列里混着少量脏值(不是全是):给了 `--since`/`--until` 时
|
|
535
|
+
这些脏值行被时间过滤排除在 `rows` 与 `data_coverage` 之外,`warnings` 会点名数量。
|
|
536
|
+
⚠️ **它只有首尾两点,看不见内部缺口**——7 天里只有第 1、7 天有数据时照样报满区间。
|
|
537
|
+
`iso-day` 表在**给了 `--since`/`--until` 时**另有 `warnings` 兜底(「区间内应有 N 个自然日,
|
|
538
|
+
实际只有 M 个有数据」),**没有时间过滤时这条兜底不触发**;`iso-instant` 与 `epoch-ms` 表
|
|
539
|
+
任何情况下都没有兜底,要核对内部覆盖得自己按自然日 `GROUP BY` 数行。
|
|
540
|
+
- `masked` / `mask_warnings` 的两个字面陷阱:`masked: true` 只表示脱敏开关开着,**不代表有值被
|
|
541
|
+
改写**(那看 `masked_columns`,为空是常态);`mask_warnings: []` 在 `--no-mask` 时**恒为空**,
|
|
542
|
+
空**不等于**脱敏完整——那是「根本没脱敏」,风险警告在 `warnings` 里。⚠️ `mask_warnings`
|
|
543
|
+
非空也**不只**意味着「脱敏不完整」:它还装脱敏对**分析结果**的影响——`GROUP BY` / `DISTINCT`
|
|
544
|
+
的**分组键**是敏感列时,不同原值会被压成同一个脱敏值(分组与计数会失真,
|
|
545
|
+
`SELECT userPhone AS p … GROUP BY p` 也照样报警;敏感列只出现在 WHERE 里不算),
|
|
546
|
+
以及非敏感列按手机号/邮箱/IPv4 形态被误改。逐条读,不要只按一种含义理解。
|
|
315
547
|
- **`--sql` 通道的数值是 JSON 安全形态的字符串**:`COUNT(*)` / `SUM` / `BIGINT` / `HUGEINT` /
|
|
316
548
|
`DECIMAL` 一律输出字符串(如 `"n":"12"`、`"d":"1.50"`),这是驱动为避免精度丢失的取舍。
|
|
317
549
|
做算术或比较前先转数字(`Number(x)`);`--table --group-by` 的 `count`、`db describe` 的
|
|
@@ -320,16 +552,42 @@ shell rc 变量。存储定位走环境变量(`QIYU_DB_PATH` 等)时,insta
|
|
|
320
552
|
(`db tables.time_range`、`db describe` 的 `unit`、`resolved_range`、`data_coverage`)呈现
|
|
321
553
|
的是 `+08:00` 形态。`--table` 通道已处理取整语义;**`--sql` 里直接按字符串比较时要用 UTC 形态**,
|
|
322
554
|
否则会少算一天(如 `WHERE stat_date >= '2026-10-12T16:00:00.000Z'`)。检测到
|
|
323
|
-
「iso-day 列 + 日期形态字面量」时 `meta.warnings`
|
|
555
|
+
「iso-day 列 + 日期形态字面量」时 `meta.warnings` 会明确提示——**只有与库内形态逐字一致
|
|
556
|
+
的 `YYYY-MM-DDT16:00:00.000Z` 才不提示**:空格分隔(`… 16:00:00.000Z`)在字典序上排在
|
|
557
|
+
`T` 之前、前导空白更小,用 `<=` 时会排除边界日甚至全表(判据看不到运算符,按方向安全一律提示)。
|
|
324
558
|
- `db tables` / `db describe` 的 `meta.notice` 恒在(本库含客户 PII 的提示);
|
|
325
559
|
声明与实况不一致(缺表/缺列/多列/时间列脏值)逐条进 `meta.warnings`,不静默——`db tables` 做表级
|
|
326
560
|
与列集核对,`db describe` 给出该表的逐列差异细节。时间列里不符合约定形态的值**不进**
|
|
327
561
|
`time_range`(否则 `not-a-date` 会在字典序上赢下 MAX),并由 warning 点名数量。
|
|
328
|
-
|
|
329
|
-
`
|
|
562
|
+
⚠️ **`columns` / `pii_columns` / `time_column` / `grain` / `primary_key` 是声明,不是库里
|
|
563
|
+
的实况**:表被删、列被删或多出列时它们照旧原样输出,差异只在 `warnings` 里。
|
|
564
|
+
`row_count` 与 `time_range` 则是**实测**(真去库里查)。`db tables` 的 `tables` 数组同理
|
|
565
|
+
**只含库中真实存在的表**——声明有而库中无的表不在这里,只在 `warnings` 里点名。
|
|
566
|
+
逐键释义见输出的 `meta.field_notes`。
|
|
567
|
+
|
|
568
|
+
`stats fields <报表>` 的输出把**声明**与**观测**分开:`table`(回显本次统计的报表表名,
|
|
569
|
+
不是「库里有哪张表」的依据)、`declared`(每条带 `source`:
|
|
330
570
|
`design-doc` 实测 / `name-suffix` 命名推断)、`observed`(`rows_present` / `minus_one` /
|
|
331
571
|
`nulls` / `min` / `max`)、`unknown_fields`(判不出单位的字段)、`sentinel`
|
|
332
|
-
(`-1` =
|
|
572
|
+
(`-1` = 该窗口或筛选条件没有匹配到数据,**不是负数比率**)。
|
|
573
|
+
|
|
574
|
+
**`declared` 的取值**(Agent 按值分支;每个值都带释义与动作,见 `meta.field_notes`;
|
|
575
|
+
本图例与源码枚举由 `tests/stats-field-notes.test.ts` 双向核对):
|
|
576
|
+
|
|
577
|
+
`declared.<字段>.unit` —— `ratio` 比率(实测样本 `assignedRatio=0.987` 是 0–1 的小数、
|
|
578
|
+
**不是** 0–100 的百分数;但只有该字段经实测,其余 `ratio` 是命名推断,而 `observed` 的
|
|
579
|
+
min/max **只能核对一致性、不是量纲证据** —— 量纲不明确时报告原值并标注不确定,不要自行
|
|
580
|
+
换算成百分比)/ `count` 计数 / `ms` 毫秒(实测 `loginDuration` 天粒度 = 86400024)/
|
|
581
|
+
`unknown` 判不出单位 —— **不是「没有单位」**,如实写「单位未知」、不要猜,这些字段同时
|
|
582
|
+
列在 `unknown_fields`。
|
|
583
|
+
|
|
584
|
+
`declared.<字段>.source` —— `design-doc` 设计稿实测明说(可信度最高)/ `name-suffix`
|
|
585
|
+
按字段名后缀推断(`*Ratio`/`*Radio`→`ratio`、`*Count`/`sessions`→`count`、
|
|
586
|
+
`*Duration`/`*Time`→`ms`)—— **是命名推断,不是实测**。
|
|
587
|
+
|
|
588
|
+
`declared.<字段>.higher_is_better` —— **恒为 `null`**:设计稿与本 CLI 都没有
|
|
589
|
+
「越大越好还是越小越好」的上游依据,不猜;不要把 `null` 读成「本字段恰好没测到」或
|
|
590
|
+
把它当 `false`,判断趋势好坏只能由人给口径。`-1` 是厂商未文档化的哨兵值,
|
|
333
591
|
`observed.minus_one` 与 `rows_present` 相等时说明该字段本次全是哨兵。
|
|
334
592
|
⚠️ 这是**聚合观测,不是逐行取值**:`rows_present` 为 1 时 `min` 与 `max` 都等于那一行的原值
|
|
335
593
|
(例:薪资明细表只有一行时,极值就是该行金额);`min`/`max` **排除 `-1` 哨兵**,因此某字段
|
|
@@ -341,8 +599,11 @@ shell rc 变量。存储定位走环境变量(`QIYU_DB_PATH` 等)时,insta
|
|
|
341
599
|
|
|
342
600
|
- **危险操作硬门禁**:标记为 `dangerous` 的接口在缺少 `--yes` 时,**绝不发出任何请求**:body 合法则返回退出码 4,body 缺必填/非对象则**先**报参数错误(退出码 2),并给出 `confirm_required` / `confirm_arg` / `risk` / `target` 四个字段。
|
|
343
601
|
危险接口不可自动重试——避免人工确认过的不可逆操作被自动重放。
|
|
344
|
-
-
|
|
345
|
-
|
|
602
|
+
- **凭证不外泄(请求/响应链路的输出)**:从请求 URL、服务端 message、网络异常里出来的文本,
|
|
603
|
+
在透出前都会把当前 `appKey` / `appSecret` / `checksum` 抹成 `<已隐藏>`;`auth whoami`
|
|
604
|
+
连末尾四位都不回显。⚠️ 边界:CLI **不扫描你自己的命令行参数**——把凭证直接敲进 argv
|
|
605
|
+
(或把它设成 `--profile` / `QIYU_PROFILE` 的名字)会原样出现在用法错误的回显里,
|
|
606
|
+
这也正是 `auth login` 拒绝 `--app-key` 的原因。
|
|
346
607
|
- **服务端内部信息过滤**:服务端偶发的错误消息里会泄漏 Java 包名/类名与请求 id,
|
|
347
608
|
透出前一律替换为占位符。
|
|
348
609
|
- **查询默认脱敏**:`query` 两条通道都默认脱敏(`sensitive: true` 的列),
|
|
@@ -359,8 +620,10 @@ shell rc 变量。存储定位走环境变量(`QIYU_DB_PATH` 等)时,insta
|
|
|
359
620
|
⚠️ 这些是**警告不是防护**:`--sql` 通道的 payload 缺口只能靠 Agent 读到警告后改用
|
|
360
621
|
`--table` 或 `--no-mask` 显式承担风险来闭合,CLI 无法在保持报表 payload 可用的前提下
|
|
361
622
|
替你做整值替换。
|
|
362
|
-
- **只读沙箱三层缺一不可**:`query --sql`
|
|
363
|
-
|
|
623
|
+
- **只读沙箱三层缺一不可**:`query --sql` 只接受单条**只读语句**——DuckDB 判为只读的形态都放行
|
|
624
|
+
(`SELECT` / `DESCRIBE` / `SHOW` / `EXPLAIN` / `PRAGMA` 查询 / `VALUES` / `TABLE <表>` / `FROM <表>`;
|
|
625
|
+
实测 2026-11-09),拒绝的是非只读类型(写操作、`SET`/`CALL` 之类的实例配置、`PRAGMA x='y'`
|
|
626
|
+
这类解析成 SET 的赋值);
|
|
364
627
|
每实例首次连接时 `enable_external_access=false` + `lock_configuration=true`,
|
|
365
628
|
实例 `access_mode=READ_ONLY`。文件读写、网络、`ATTACH`、`COPY TO`、多语句全部被拦;
|
|
366
629
|
`EXPLAIN ANALYZE` 也拒(它会真正执行内层语句)。
|
|
@@ -382,15 +645,41 @@ shell rc 变量。存储定位走环境变量(`QIYU_DB_PATH` 等)时,insta
|
|
|
382
645
|
查询与只读沙箱——`db tables` / `db describe` / `query --sql` / `query --table` / `stats fields`
|
|
383
646
|
(三层只读沙箱、默认脱敏、时间列三形态语义化、`-1` 哨兵呈现、声明与观测分离)。
|
|
384
647
|
Skill 化——`skill install`(复制正文 + 建 Agent 链接,幂等,`--dry-run` 只算计划)/
|
|
385
|
-
`skill check
|
|
386
|
-
|
|
387
|
-
`
|
|
388
|
-
`
|
|
648
|
+
`skill check`(校验正文引用的命令、flag、错误 `kind` 与位置参数取值是否与 CLI 契约一致,
|
|
649
|
+
并拒绝正文里硬编码表名或完整 SQL 关键字序列;`--installed`/`--compare` 改基准;
|
|
650
|
+
有违规退出码 1,`--compare` 下内容不一致也算失败)/
|
|
651
|
+
`skill where`(只读报告实体目录与各 Agent 链接状态),
|
|
389
652
|
外加 `qiyu --version`(输出包版本与 `skill_contract_version`)。
|
|
390
653
|
|
|
654
|
+
**`skill` 输出的状态取值**(Agent 按值分支;命令输出里每个值都带释义与动作,见
|
|
655
|
+
`meta.field_notes`;本图例与源码枚举由 `tests/skill-field-notes.test.ts` 三方核对):
|
|
656
|
+
|
|
657
|
+
`data.entity.state`(`skill where`)——`ok` 实体目录可用 / `missing` 不存在(= 未安装)/
|
|
658
|
+
`not_a_directory` 路径存在但不是目录(install 不会写它,需人先处理)/
|
|
659
|
+
`unknown` 无法判定(带 `error`,此时 `exists` 为 `null`)—— **`unknown` 不是「不存在」**。
|
|
660
|
+
|
|
661
|
+
`data.links[].state`(`skill where` 与 `skill install`)——`ok` 正确指向本实体 /
|
|
662
|
+
`missing` 链接不存在(**install 只在该 Agent 的 skills 目录已存在时**创建链接,从不创建
|
|
663
|
+
目录;目录不存在时 install 在 `meta.warnings` 里说明,且 `links` 里没有这个 Agent 的条目)/
|
|
664
|
+
`dangling` 链接存在但目标已不在(install 会重建)/
|
|
665
|
+
`foreign` **路径上是别人的东西**(不是指向本实体的符号链接,install 一律跳过,**不要删**)/
|
|
666
|
+
`unknown` 无法判定(带 `error`)——同样**不是「不存在」**。
|
|
667
|
+
|
|
668
|
+
`skill install --dry-run` 的 `data.action` / `data.planned_status`——`install`/`installed`
|
|
669
|
+
首次安装;`update`/`updated` 覆盖正文(`--force`)或只重写落后的清单;`skip`/`skipped`
|
|
670
|
+
**实体正文零写入**(内容一致且清单新鲜,或内容不同但没带 `--force`,原因在 `meta.warnings`)。
|
|
671
|
+
⚠️ 零写入只针对**实体正文**:链接仍会照常建立/修复 —— 实测「删掉链接后重装」返回
|
|
672
|
+
`status: skipped` 且 `links[].state` 回到 `ok`。判断链接发生了什么要看 `links[]`。
|
|
673
|
+
真实安装用 `data.status`(`installed`/`updated`/`skipped`,语义同上);`links[].action`
|
|
674
|
+
是**计划动作**(`keep`/`create`/`rebuild`/`skip`/`unknown`,与 `links[].state` 一一对应),
|
|
675
|
+
只在 `--dry-run` 的输出里存在 —— 真实安装的 `links[]` 条目只有 `state` 与可选 `error`。
|
|
676
|
+
|
|
391
677
|
body 分级校验:`api call` 的 `--body` 与注册表参数表比对——缺必填拒绝(退出码 2),
|
|
392
678
|
未知字段/类型不符出 `meta.warnings`;`--strict` 可升级、`--no-validate` 可关闭。
|
|
393
679
|
参数表见 `qiyu api schema <id>`(`data.params`、`data.response_shape`)。
|
|
680
|
+
`data.params[]` 的元素字段是 `in`(`query` / `body` / `path` / `header`)、`required`、
|
|
681
|
+
`type`、`description`、`example`,以及条件出现的 `auto`(**只挂在这个数组的元素上**,
|
|
682
|
+
不是 `data` 的顶层键)。
|
|
394
683
|
只依据文档生成的参数表,不构成对服务端行为的保证;**响应体不做校验**;
|
|
395
684
|
校验只对 `body_kind: json` 且有 body 参数表的接口生效,其余原样透传。
|
|
396
685
|
`--strict` 只做本地参数表闭集一致性检查(「严格」≠「正确严格」),误拒时**不要删字段重试**。
|
|
@@ -399,7 +688,10 @@ body 分级校验:`api call` 的 `--body` 与注册表参数表比对——缺
|
|
|
399
688
|
写在**具体子命令之后**(如 `qiyu api list --pretty`)。Agent 不需要它:默认输出已是合法 JSON,
|
|
400
689
|
缩进只是给人看的。用法错误(退出码 2)仍是紧凑 JSON —— 先修参数,再看格式。
|
|
401
690
|
|
|
402
|
-
`api list` 输出的 `
|
|
691
|
+
`api list` 输出的 `data` 是**行数组**(`[{id, title, …}, …]`,不是 `{rows:[…]}` 对象)——
|
|
692
|
+
`meta.field_notes` 的键是**行字段名**(`verified` / `dangerous` / `direction` …),
|
|
693
|
+
唯一的例外是 `request_schema`:它不是字段,而是一条「本 meta 不含参数表,去
|
|
694
|
+
`api schema` 查」的否定声明。`meta.registry_complete` 会如实反映注册表是否已收录全部接口。
|
|
403
695
|
|
|
404
696
|
## 浏览器 / 文档
|
|
405
697
|
|