qiyu-cli 0.0.0-stage → 0.2.0
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 +464 -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 +863 -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 +18 -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 +336 -0
- package/dist/skill/install.js +1202 -0
- package/dist/skill/paths.js +343 -0
- package/dist/skill/qiyu/SKILL.md +86 -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
|
@@ -0,0 +1,343 @@
|
|
|
1
|
+
// src/skill/paths.ts —— agent skills 目录探测、实体目录默认位置、链接目标计算、
|
|
2
|
+
// 链接四态判定,以及跨平台链接创建与换行归一化。
|
|
3
|
+
//
|
|
4
|
+
// 本文件是 `src/skill/` 叶子层:只用 `node:*` 标准库,不 import `commands/`、`store/`、
|
|
5
|
+
// `core/`,也不被它们反向 import。消费方是 Task 9(安装,用 `LinkState` 填
|
|
6
|
+
// `InstallResult.links[].state`)与 Task 11(`skill where` 直接展示四态)。
|
|
7
|
+
//
|
|
8
|
+
// **注入 home / 注入 env,不读真实环境**:所有路径函数都收调用方给的 `home`,键名
|
|
9
|
+
// 归一化函数收调用方给的 `env`(`postinstall.ts` 传 `opts.env`、`detect.ts` 传
|
|
10
|
+
// `process.env`),本文件不读 `~`、**不直接**读 `process.env`,测试因此可以完全
|
|
11
|
+
// 跑在临时目录与字面量 env 里。唯一的平台依赖是 `createSkillLink` 里的
|
|
12
|
+
// `process.platform`,而平台决策本身已抽成纯函数 `linkPlan`,测试可以直接注入
|
|
13
|
+
// 平台值来钉住行为。
|
|
14
|
+
//
|
|
15
|
+
// 链接四态(linkState):
|
|
16
|
+
// · missing —— 链接路径本身不存在(lstat ENOENT)。
|
|
17
|
+
// · foreign —— 路径存在但不是符号链接,或者是指向别处的符号链接:这块位置被
|
|
18
|
+
// 别的东西占了,安装时不能覆盖、要报给用户看。链接目标真实存在、但实体目录
|
|
19
|
+
// 自己不存在时,也是 foreign(2026-10-22 审查 Minor #2)。
|
|
20
|
+
// · dangling —— 是符号链接,但链接目标解析不到(实体目录被删了)。
|
|
21
|
+
// · ok —— 是符号链接且解析后指向实体目录。
|
|
22
|
+
// 判定必须用 `lstatSync` 而不是 `statSync`:`statSync` 会顺着链接走,链接本身与
|
|
23
|
+
// 「链接指向的东西」就分不开了 —— 而四态的全部意义正是区分这两者。
|
|
24
|
+
import { lstatSync, realpathSync, statSync } from 'node:fs';
|
|
25
|
+
import { symlink } from 'node:fs/promises';
|
|
26
|
+
import path from 'node:path';
|
|
27
|
+
/**
|
|
28
|
+
* 安装清单文件名:落在实体目录根部,记录版本与内容哈希(`install.ts` 写、
|
|
29
|
+
* `detect.ts` 与 `install.ts` 读)。
|
|
30
|
+
*
|
|
31
|
+
* 它是**路径事实**,所以收敛在 paths.ts 这个事实源里(G4/D6):此前 `install.ts` 与
|
|
32
|
+
* `scripts/copy-assets.mjs` 各写一份字面量,改一处必漏另一处。`install.ts` 仍 re-export
|
|
33
|
+
* 以保持既有 import 路径兼容;`copy-assets.mjs` 是纯 JS 构建脚本(不能 import TS),
|
|
34
|
+
* 两侧字面量的一致性由 `tests/skill/constants.test.ts` 的交叉校验用例钉住。
|
|
35
|
+
*/
|
|
36
|
+
export const MANIFEST = '.qiyu-skill.json';
|
|
37
|
+
/**
|
|
38
|
+
* agent skills 目录下的链接名。skill 身份固定为 `qiyu`(正文 frontmatter 同名),
|
|
39
|
+
* 不随实体位置变化。
|
|
40
|
+
*
|
|
41
|
+
* 本常量是**路径事实**,所以放在 paths.ts 这个路径事实源里:`install.ts`(安装)
|
|
42
|
+
* 与 `commands/skill.ts`(`--dry-run`/`where` 的计划与探测)都从这里取,避免两份
|
|
43
|
+
* 字符串镜像各自漂移(终审 Minor-1)。
|
|
44
|
+
*/
|
|
45
|
+
export const LINK_NAME = 'qiyu';
|
|
46
|
+
/**
|
|
47
|
+
* 已知 agent → 它存放 skills 的目录(相对 `home`)。
|
|
48
|
+
*
|
|
49
|
+
* 用 `Record<AgentDir['name'], string>` 而不是数组:新增/重命名 agent 时联合类型
|
|
50
|
+
* 会让这里编译失败,子目录字符串因此有编译期保护(终审 Minor-2 要求保留)。
|
|
51
|
+
*/
|
|
52
|
+
const AGENT_SKILL_SUBDIR_BY_NAME = {
|
|
53
|
+
'claude-code': path.join('.claude', 'skills'),
|
|
54
|
+
codex: path.join('.codex', 'skills'),
|
|
55
|
+
};
|
|
56
|
+
/**
|
|
57
|
+
* 已知 agent 及其 skills 目录相对 `home` 的位置,按展示顺序排列。
|
|
58
|
+
*
|
|
59
|
+
* 从上面的 `Record` 派生(而不是另写一份数组),消费方是 `agentSkillDirs()` 与
|
|
60
|
+
* `commands/skill.ts` 的 ENOTDIR 退化探测——两处看到的是同一份事实。
|
|
61
|
+
*/
|
|
62
|
+
export const AGENT_SKILL_SUBDIRS = Object.keys(AGENT_SKILL_SUBDIR_BY_NAME).map((name) => ({
|
|
63
|
+
name,
|
|
64
|
+
subdir: AGENT_SKILL_SUBDIR_BY_NAME[name],
|
|
65
|
+
}));
|
|
66
|
+
/**
|
|
67
|
+
* 按 agent 名取 skills 子目录(相对 `home`)。消费方是 `commands/skill.ts` 的
|
|
68
|
+
* ENOTDIR 退化探测与 `skill where` 的 missing 条目——它们手里只有 agent 名。
|
|
69
|
+
*/
|
|
70
|
+
export function agentSkillSubdir(name) {
|
|
71
|
+
return AGENT_SKILL_SUBDIR_BY_NAME[name];
|
|
72
|
+
}
|
|
73
|
+
/**
|
|
74
|
+
* 返回 `home` 下**已存在**的 agent skills 目录。不存在的 agent 不返回 ——
|
|
75
|
+
* 调用方据此决定「这个 agent 没装,跳过」,而不是替它建目录。
|
|
76
|
+
*/
|
|
77
|
+
export function agentSkillDirs(home) {
|
|
78
|
+
const result = [];
|
|
79
|
+
for (const { name, subdir } of AGENT_SKILL_SUBDIRS) {
|
|
80
|
+
const dir = path.join(home, subdir);
|
|
81
|
+
if (exists(dir))
|
|
82
|
+
result.push({ name, dir });
|
|
83
|
+
}
|
|
84
|
+
return result;
|
|
85
|
+
}
|
|
86
|
+
/**
|
|
87
|
+
* 装了 Agent 根目录(如 `~/.claude`)但没有 skills 子目录的 agent,返回其**缺失的**
|
|
88
|
+
* skills 目录路径(不创建)。消费方是 `install.ts`:自动模式下一条链接都没建时,
|
|
89
|
+
* 用它区分「这台机器上根本没有 Agent」(正常,不告警)与「Agent 装了、但 skills
|
|
90
|
+
* 子目录还没建」(审查 B3:此前静默不建链、零警告,用户拿到的是「装好了」)。
|
|
91
|
+
*
|
|
92
|
+
* 根目录也不存在(`~/.claude` 本身就没有、或是文件)的 agent 不返回——那不是
|
|
93
|
+
* 「可以修」的状态,是没装。
|
|
94
|
+
*/
|
|
95
|
+
export function agentsMissingSkillDir(home) {
|
|
96
|
+
const result = [];
|
|
97
|
+
for (const { name, subdir } of AGENT_SKILL_SUBDIRS) {
|
|
98
|
+
const parts = subdir.split(path.sep);
|
|
99
|
+
const root = path.join(home, parts[0]);
|
|
100
|
+
// 根必须是**真实目录**(`~/.claude` 是文件 → ENOTDIR 不算装了 Agent)。先判根
|
|
101
|
+
// 再判子目录:根是文件时 `lstat(root/skills)` 直接抛 ENOTDIR,顺序反了会把
|
|
102
|
+
// 一个正常状态(用户没有 ~/.claude 目录)变成异常。
|
|
103
|
+
let rootIsDir;
|
|
104
|
+
try {
|
|
105
|
+
rootIsDir = statSync(root).isDirectory();
|
|
106
|
+
}
|
|
107
|
+
catch (err) {
|
|
108
|
+
if (isEnoent(err) || isEnotdir(err))
|
|
109
|
+
continue;
|
|
110
|
+
throw err;
|
|
111
|
+
}
|
|
112
|
+
if (!rootIsDir)
|
|
113
|
+
continue;
|
|
114
|
+
const dir = path.join(home, subdir);
|
|
115
|
+
if (exists(dir))
|
|
116
|
+
continue;
|
|
117
|
+
result.push({ name, dir });
|
|
118
|
+
}
|
|
119
|
+
return result;
|
|
120
|
+
}
|
|
121
|
+
/**
|
|
122
|
+
* 实体目录的默认位置:`<home>/.agents/skills/qiyu`(叶子名与 `LINK_NAME` 同一份事实,
|
|
123
|
+
* D6:此前这里另写了一个 `'qiyu'` 字面量,与链接名两处镜像)。
|
|
124
|
+
*
|
|
125
|
+
* `pathImpl` 是**平台语义注入缝**(D3.15 / D1):默认用当前平台的 `path`,测试可以传
|
|
126
|
+
* `path.win32` 在不切平台的前提下钉住 Windows 的拼接结果。注入只改变路径运算,不改变
|
|
127
|
+
* 任何目录选择。
|
|
128
|
+
*/
|
|
129
|
+
export function defaultEntityDir(home, pathImpl = path) {
|
|
130
|
+
return pathImpl.join(home, '.agents', 'skills', LINK_NAME);
|
|
131
|
+
}
|
|
132
|
+
/**
|
|
133
|
+
* 从 `agentDir` 指向 `entityDir` 的相对链接目标。用相对路径而非绝对路径,
|
|
134
|
+
* 是为了让整个 `~` 目录可以整体搬迁/复制而不失效。
|
|
135
|
+
*
|
|
136
|
+
* ⚠️ 相对路径是**相对链接所在目录的真实落点**解析的,所以 `agentDir` 必须先过
|
|
137
|
+
* `realpathSync`(stow/dotfiles 布局下 `~/.claude/skills` 本身就是符号链接,真实
|
|
138
|
+
* 落点可能与字面路径深度不同;2026-10-22 审查 B1 实测:不归一化时建出的链接指向
|
|
139
|
+
* 不存在的路径,却报 state='ok')。解析失败(目录不存在等)退回原值:此时建链本来
|
|
140
|
+
* 就会失败并进 warnings,不在这里制造第二个错误。
|
|
141
|
+
*/
|
|
142
|
+
export function linkTarget(agentDir, entityDir) {
|
|
143
|
+
return path.relative(realpathOrSelf(agentDir), entityDir);
|
|
144
|
+
}
|
|
145
|
+
/** `realpathSync` 的「失败即退回原值」版本(供 linkTarget 使用,见其注释)。 */
|
|
146
|
+
function realpathOrSelf(p) {
|
|
147
|
+
try {
|
|
148
|
+
return realpathSync(p).toString();
|
|
149
|
+
}
|
|
150
|
+
catch {
|
|
151
|
+
return p;
|
|
152
|
+
}
|
|
153
|
+
}
|
|
154
|
+
/**
|
|
155
|
+
* 判定 `linkPath` 相对 `entityDir` 的状态。
|
|
156
|
+
*
|
|
157
|
+
* 判「是不是同一个目录」用 **dev + ino**(`statSync` 两边,顺着链接走),不比较
|
|
158
|
+
* 路径字符串:macOS 默认 APFS 是大小写不敏感卷,而 `realpathSync` **不做大小写
|
|
159
|
+
* 归一化**(磁盘上是 `Qiyu`、传入 `qiyu`,realpath 只会把后者原样拼回去)——
|
|
160
|
+
* 字符串严格比较会把同一个目录判成 foreign,让 `where` 报错、让 install 拒绝修复
|
|
161
|
+
* 一条其实 ok 的链接(2026-10-22 审查 Minor #36 实测)。同 inode 判定对大小写不
|
|
162
|
+
* 敏感卷、大小写敏感卷、bind mount、符号链接都成立。
|
|
163
|
+
*
|
|
164
|
+
* inode 读不到(EACCES 等)时退回 realpath + `path.resolve` 的字符串比较;那种
|
|
165
|
+
* 环境下也读不到链接目标,调用方本来就会按异常收敛。
|
|
166
|
+
*
|
|
167
|
+
* 注意:自指或成环的符号链接(realpath 解析超过系统上限)会抛 ELOOP,**不落四态** ——
|
|
168
|
+
* ELOOP 不在内部吞掉的错误之列(`lstatOrNull` 只吞 ENOENT,`statOrNull`/`realpathOrNull`
|
|
169
|
+
* 只吞 ENOENT/ENOTDIR,其余一律照常抛)。Task 11 的 `skill where`
|
|
170
|
+
* 若要在这种异常环境下仍然给出可读输出,需要自己在调用处兜住。
|
|
171
|
+
*/
|
|
172
|
+
export function linkState(linkPath, entityDir) {
|
|
173
|
+
const stat = lstatOrNull(linkPath);
|
|
174
|
+
if (stat === null)
|
|
175
|
+
return 'missing';
|
|
176
|
+
if (!stat.isSymbolicLink())
|
|
177
|
+
return 'foreign';
|
|
178
|
+
// 顺着链接走:目标解析不到 → 链接悬空。ELOOP 不吞(自指/成环不落四态,见函数
|
|
179
|
+
// 注释)——判定不了就如实抛,由调用方按「不触碰、只报告」处理。
|
|
180
|
+
const linkTargetStat = statOrNull(linkPath);
|
|
181
|
+
if (linkTargetStat === null)
|
|
182
|
+
return 'dangling';
|
|
183
|
+
const entityStat = statOrNull(entityDir);
|
|
184
|
+
// 实体目录自己不存在,但链接目标**能**解析到(说明它指向别处一个真实存在的东西)
|
|
185
|
+
// —— 按四态语义是 foreign(「路径存在但不是指向我们的链接」)。2026-10-22 审查
|
|
186
|
+
// Minor #2/#7 实测:此前这里在解析目标之前就短路成 dangling,导致 `where` 报
|
|
187
|
+
// dangling / dry-run 预告 rebuild,而真实安装(装好实体后再判定)报 foreign 并
|
|
188
|
+
// 拒绝覆盖——同一链接两种说法。
|
|
189
|
+
if (entityStat === null)
|
|
190
|
+
return 'foreign';
|
|
191
|
+
// 首选的判据:同一 inode(见函数注释)。只有两侧都拿到了 inode 才用。
|
|
192
|
+
if (hasInode(linkTargetStat) && hasInode(entityStat)) {
|
|
193
|
+
return linkTargetStat.dev === entityStat.dev && linkTargetStat.ino === entityStat.ino
|
|
194
|
+
? 'ok'
|
|
195
|
+
: 'foreign';
|
|
196
|
+
}
|
|
197
|
+
// 兜底:realpath 后按字符串比(realpath 抛错已在上面 statOrNull 阶段被吞成 null)。
|
|
198
|
+
const resolvedLink = realpathOrNull(linkPath);
|
|
199
|
+
const resolvedEntity = realpathOrNull(entityDir);
|
|
200
|
+
if (resolvedLink === null || resolvedEntity === null)
|
|
201
|
+
return 'foreign';
|
|
202
|
+
return path.resolve(resolvedLink) === path.resolve(resolvedEntity) ? 'ok' : 'foreign';
|
|
203
|
+
}
|
|
204
|
+
/** `Stats` 是否带可用的 inode 数字(Windows 的 stat 也有 ino,但为 0 时不可比)。 */
|
|
205
|
+
function hasInode(st) {
|
|
206
|
+
return typeof st.ino === 'number' && st.ino !== 0 && typeof st.dev === 'number';
|
|
207
|
+
}
|
|
208
|
+
/**
|
|
209
|
+
* 平台决策的纯函数:给定链接路径、目标与平台,返回实际要传给 `symlink` 的参数。
|
|
210
|
+
*
|
|
211
|
+
* Windows 的 junction 只接受**绝对路径**,所以 win32 上把相对 target 按
|
|
212
|
+
* `dirname(linkPath)` 解析成绝对路径,并指定 type `'junction'`;其他平台原样
|
|
213
|
+
* 保留相对 target、不指定 type(POSIX 下 Node 会自行判断 file/dir)。
|
|
214
|
+
*
|
|
215
|
+
* `pathImpl` 是**平台语义注入缝**(D3.15,与 `defaultEntityDir` 同一个理由):默认用
|
|
216
|
+
* 当前平台的 `path`(行为与以前逐字相同),测试可以传 `path.win32` 并用 win32 形态的
|
|
217
|
+
* 输入,在不切平台的前提下钉住 Windows 分支真正走的是 win32 的路径运算
|
|
218
|
+
* ——此前那条「win32」用例在 POSIX 机器上实际跑的是 POSIX `path.resolve`。
|
|
219
|
+
*
|
|
220
|
+
* ⚠️ Windows 上 junction 的真实行为未在本机实测(spec §跨平台 已声明未覆盖);
|
|
221
|
+
* 这里保证的只是决策逻辑本身,由用例钉住。
|
|
222
|
+
*/
|
|
223
|
+
export function linkPlan(linkPath, target, platform, pathImpl = path) {
|
|
224
|
+
if (platform === 'win32') {
|
|
225
|
+
// ⚠️ 解析基准必须是链接所在目录的**真实落点**:junction 的 target 是绝对路径,
|
|
226
|
+
// 而相对 target 是相对「链接实际所在的那个目录」解析的——agent 目录本身是符号
|
|
227
|
+
// 链接时,字面路径与真实落点深度不同(审查 B1 的同一根因)。realpath 失败
|
|
228
|
+
// (目录还不存在等)退回字面路径,与旧行为一致。
|
|
229
|
+
return { target: pathImpl.resolve(realpathOrSelf(pathImpl.dirname(linkPath)), target), type: 'junction' };
|
|
230
|
+
}
|
|
231
|
+
return { target };
|
|
232
|
+
}
|
|
233
|
+
/**
|
|
234
|
+
* 在 `linkPath` 创建指向 `target` 的链接。平台相关的一切都交给 `linkPlan`,
|
|
235
|
+
* 这里只做一次 `symlink` 调用。调用方负责保证 `linkPath` 的父目录存在,
|
|
236
|
+
* 以及 `linkPath` 当前不是已存在的东西(`symlink` 本身遇到已存在路径会 EEXIST)。
|
|
237
|
+
*
|
|
238
|
+
* `target` 必须是 `linkTarget(agentDir, entityDir)` 的计算结果——`linkPlan` 在
|
|
239
|
+
* win32 上按 `dirname(linkPath)` 解析相对 target,这个写法只在链接目录与
|
|
240
|
+
* `agentDir` 同一字符串时才成立(调用方传的就是同一个 `dir`)。
|
|
241
|
+
* 成功后调用方**必须**用 `linkState` 复核(审查 B1),本函数不替调用方判定。
|
|
242
|
+
*/
|
|
243
|
+
export async function createSkillLink(linkPath, target) {
|
|
244
|
+
const plan = linkPlan(linkPath, target, process.platform);
|
|
245
|
+
await symlink(plan.target, linkPath, plan.type);
|
|
246
|
+
}
|
|
247
|
+
/**
|
|
248
|
+
* 把 CRLF 折成 LF。skill 正文会跨平台分发,Windows 侧产出的 CRLF 不应污染
|
|
249
|
+
* 内容比较与哈希。
|
|
250
|
+
*
|
|
251
|
+
* 按字节处理而不是解码成字符串:UTF-8 多字节字符可能被 0x0D/0x0A 字节序列
|
|
252
|
+
* 切断的顾虑不存在(UTF-8 续字节都 ≥ 0x80),字节级替换对任意内容都无损;
|
|
253
|
+
* 孤立的 `\r`(不是 CRLF 的一部分)原样保留 —— 本函数只承诺 CRLF → LF。
|
|
254
|
+
*/
|
|
255
|
+
export function normalizeNewlines(buf) {
|
|
256
|
+
const out = Buffer.alloc(buf.length);
|
|
257
|
+
let n = 0;
|
|
258
|
+
for (let i = 0; i < buf.length; i++) {
|
|
259
|
+
if (buf[i] === 0x0d && i + 1 < buf.length && buf[i + 1] === 0x0a)
|
|
260
|
+
continue;
|
|
261
|
+
out[n++] = buf[i];
|
|
262
|
+
}
|
|
263
|
+
return out.subarray(0, n);
|
|
264
|
+
}
|
|
265
|
+
// —— 环境变量(键名归一化) ——
|
|
266
|
+
/**
|
|
267
|
+
* 把 env 的键统一成「小写 + `-` 转 `_`」后建索引(spec D8:Windows 环境变量名
|
|
268
|
+
* 大小写不敏感;npm 自己会把配置名里的 `-` 归一化成 `_`,于是
|
|
269
|
+
* `npm_config_qiyu-skill-dir` / `NPM_CONFIG_QIYU_SKILL_DIR` 都命中同一键)。
|
|
270
|
+
* 只收字符串值——`NodeJS.ProcessEnv` 的值类型允许 undefined,未定义的键视同不存在。
|
|
271
|
+
*
|
|
272
|
+
* 导出而不是在 `postinstall.ts` 与 `detect.ts` 各写一份:postinstall 用
|
|
273
|
+
* `npm_config_qiyu_skill_dir` 决定「装到哪」,漂移探测用它决定「去哪找」——两处
|
|
274
|
+
* 的归一化规则一旦不同,装上之后的每条命令都会误报「未安装」(终审 I2)。
|
|
275
|
+
*/
|
|
276
|
+
export function envIndex(env) {
|
|
277
|
+
const index = new Map();
|
|
278
|
+
for (const [key, value] of Object.entries(env)) {
|
|
279
|
+
if (typeof value !== 'string')
|
|
280
|
+
continue;
|
|
281
|
+
index.set(normalizeEnvKey(key), value);
|
|
282
|
+
}
|
|
283
|
+
return index;
|
|
284
|
+
}
|
|
285
|
+
/**
|
|
286
|
+
* 按归一化键读一个环境变量,空串/纯空白视同未设(与既有 `QIYU_SKILL_DIR` 口径一致),
|
|
287
|
+
* 返回值已 trim。`key` 自身也过同一归一化,调用方写哪种拼法都行。
|
|
288
|
+
*/
|
|
289
|
+
export function readEnvByNormalizedKey(env, key) {
|
|
290
|
+
const value = envIndex(env).get(normalizeEnvKey(key))?.trim();
|
|
291
|
+
return value !== undefined && value !== '' ? value : undefined;
|
|
292
|
+
}
|
|
293
|
+
function normalizeEnvKey(key) {
|
|
294
|
+
return key.toLowerCase().replace(/-/g, '_');
|
|
295
|
+
}
|
|
296
|
+
// —— 内部工具 ——
|
|
297
|
+
/** lstat 的「不存在即 null」版本:只吞 ENOENT,其他错误照常抛。 */
|
|
298
|
+
function lstatOrNull(p) {
|
|
299
|
+
try {
|
|
300
|
+
return lstatSync(p);
|
|
301
|
+
}
|
|
302
|
+
catch (err) {
|
|
303
|
+
if (isEnoent(err))
|
|
304
|
+
return null;
|
|
305
|
+
throw err;
|
|
306
|
+
}
|
|
307
|
+
}
|
|
308
|
+
/** realpath 的「解析不到即 null」版本:只吞 ENOENT/ENOTDIR,其他错误照常抛。 */
|
|
309
|
+
function realpathOrNull(p) {
|
|
310
|
+
try {
|
|
311
|
+
return realpathSync(p).toString();
|
|
312
|
+
}
|
|
313
|
+
catch (err) {
|
|
314
|
+
if (isEnoent(err) || isEnotdir(err))
|
|
315
|
+
return null;
|
|
316
|
+
throw err;
|
|
317
|
+
}
|
|
318
|
+
}
|
|
319
|
+
/**
|
|
320
|
+
* `statSync`(**顺着**链接走)的「拿不到即 null」版本:吞 ENOENT/ENOTDIR。
|
|
321
|
+
* ELOOP **不吞**——成环链接在 `linkState` 里是「判定不了」,不是「目标不存在」
|
|
322
|
+
* (四态不覆盖这种情况,调用方按 foreign/unknown 处理)。其余错误照常抛。
|
|
323
|
+
*/
|
|
324
|
+
function statOrNull(p) {
|
|
325
|
+
try {
|
|
326
|
+
return statSync(p);
|
|
327
|
+
}
|
|
328
|
+
catch (err) {
|
|
329
|
+
if (isEnoent(err) || isEnotdir(err))
|
|
330
|
+
return null;
|
|
331
|
+
throw err;
|
|
332
|
+
}
|
|
333
|
+
}
|
|
334
|
+
/** 目录项是否存在(存在即可,不区分文件/目录/链接)。 */
|
|
335
|
+
function exists(p) {
|
|
336
|
+
return lstatOrNull(p) !== null;
|
|
337
|
+
}
|
|
338
|
+
function isEnoent(err) {
|
|
339
|
+
return typeof err === 'object' && err !== null && err.code === 'ENOENT';
|
|
340
|
+
}
|
|
341
|
+
function isEnotdir(err) {
|
|
342
|
+
return typeof err === 'object' && err !== null && err.code === 'ENOTDIR';
|
|
343
|
+
}
|
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: qiyu
|
|
3
|
+
description: 查询与分析网易七鱼客服数据(会话、工单、知识库、统计报表)的 CLI 使用协议——先同步本地库再查,事实一律运行时获取。
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# 七鱼数据操作手册
|
|
7
|
+
|
|
8
|
+
本 skill 教你在七鱼(网易七鱼客服系统)数据上正确工作:查会话、查工单、查知识库、算统计报表。
|
|
9
|
+
所有表名、列名、接口清单、指标单位都**不写死在本 skill 里**——用 CLI 的自描述在运行时获取,
|
|
10
|
+
因为写死的名字会随版本漂移,而猜错是静默失败。
|
|
11
|
+
|
|
12
|
+
## 开场协议:任何数据任务的第一步
|
|
13
|
+
|
|
14
|
+
```
|
|
15
|
+
qiyu sync status
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
它给出每条同步任务的水位、上次成功同步时间、实际覆盖区间、缺口与锁。在看过它之前,
|
|
19
|
+
不要对数据下任何结论。**如果所有任务的水位与覆盖区间都是 null**(说明还没有成功同步过),
|
|
20
|
+
先跑 `qiyu sync run`,跑完再看。(安装调度时,`sync install` 的前置探测会以
|
|
21
|
+
`kind: sync_not_run` 报同一事实。)
|
|
22
|
+
|
|
23
|
+
拿到覆盖范围后,按需自描述:
|
|
24
|
+
|
|
25
|
+
- 有哪些表、行数、粒度、时间范围、PII 标注:`qiyu db tables`
|
|
26
|
+
- 单表的列定义:`qiyu db describe <表>`
|
|
27
|
+
- 报表指标的单位、本地观测分布、哨兵值:`qiyu stats fields <报表表>`
|
|
28
|
+
- 接口清单与参数表:`qiyu api list`、`qiyu api schema <接口id>`
|
|
29
|
+
- 同步任务清单:`qiyu sync tasks`
|
|
30
|
+
- 凭证是否已配置:`qiyu auth whoami`
|
|
31
|
+
- 库状态与各表行数:`qiyu store status`
|
|
32
|
+
|
|
33
|
+
## 这份协议自己的安装与配套
|
|
34
|
+
|
|
35
|
+
本 skill 是随 CLI 分发的正文,装到本机后可能与包内那份不一致。以下三件事都靠 CLI 回答,
|
|
36
|
+
不要凭记忆判断。
|
|
37
|
+
|
|
38
|
+
- **`meta.warnings` 里的 skill 提示**:任何一条成功输出都可能带一句「skill 未安装」或
|
|
39
|
+
「skill 已过期」。它只提示、不改退出码、不改 `data`,也**没有自动改过任何文件**。
|
|
40
|
+
含义是本机装的正文与这份 CLI 不配套;更新方式是 `qiyu skill install`——它会写到本机
|
|
41
|
+
的 skill 实体目录与各 Agent 的 skills 目录。**只在人类允许写 home 时执行**,不要自作主张
|
|
42
|
+
改动用户目录;不允许时把这条提示原样转述给人类。
|
|
43
|
+
- **`qiyu --version`**:输出包版本(`data.version`)与 `data.skill_contract_version`。
|
|
44
|
+
`skill_contract_version` 就是正文与 CLI 的配套约定号——用它判断手上的正文能否配这份
|
|
45
|
+
CLI,而不是拿包版本号去比。
|
|
46
|
+
- **`qiyu skill check`**:正文自身的防漂移校验(命令、表名、错误 `kind`、位置参数取值是否
|
|
47
|
+
仍存在于当前 CLI)。默认校验包内那份;`--installed` 校验已安装的那份,`--compare` 比对
|
|
48
|
+
两份并报告差异。有违规时退出码 1。
|
|
49
|
+
- **不要手工编辑已安装的正文**:下次 `qiyu skill install` 会以包内那份为准。要改就改
|
|
50
|
+
包内(发行包里的)那份,并重新安装。
|
|
51
|
+
|
|
52
|
+
## 通道路由决策树
|
|
53
|
+
|
|
54
|
+
先判断任务特征,再选通道——不要一律走 API,也不要一律查本地。
|
|
55
|
+
|
|
56
|
+
| 任务特征 | 通道 | 起点命令 |
|
|
57
|
+
|---|---|---|
|
|
58
|
+
| 历史趋势、聚合、跨天/跨窗口统计 | 本地同步库(受约束查询) | `qiyu query --table <表>` |
|
|
59
|
+
| 需要 JOIN、跨表聚合,受约束查询表达不了 | 本地同步库(只读 SQL) | `qiyu query --sql <SQL>` |
|
|
60
|
+
| 刚刚发生的事、单条记录明细 | 实时 API | `qiyu api list` 找接口 → `qiyu api call <接口id>` |
|
|
61
|
+
| 写操作(创建、修改、派发、回复等) | 实时 API(有确认闸门) | `qiyu api call <接口id> --body <JSON>` |
|
|
62
|
+
| 本地库里没有要的表 | 先补同步,或走实时 API | `qiyu db tables` 确认 → `qiyu sync run` 或 `qiyu api call <接口id>` |
|
|
63
|
+
|
|
64
|
+
三条判据:
|
|
65
|
+
|
|
66
|
+
- `qiyu query --table <表>` 是受约束通道:表名闭集校验、时间过滤、分组计数、默认脱敏。
|
|
67
|
+
**单表的行、计数、时间范围一律优先用它**。
|
|
68
|
+
- `qiyu query --sql <SQL>` 只用于受约束通道表达不了的 JOIN / 跨表聚合;拿它跑单表简单过滤
|
|
69
|
+
是绕过列白名单与精确脱敏(见 forbidden.md)。
|
|
70
|
+
- 写操作命中确认闸门时返回退出码 4 与 `kind: needs_confirmation`——停下来向人类复述操作与
|
|
71
|
+
目标,**绝不自动追加 `--yes`**(见 errors.md)。
|
|
72
|
+
|
|
73
|
+
## 输出与退出码
|
|
74
|
+
|
|
75
|
+
- stdout 只有一行 JSON:成功为 `{"ok":true,"data":…}`(部分命令附带 `"meta":…`),失败为
|
|
76
|
+
`{"ok":false,"error":…}`;日志与进度走 stderr,不要把 stderr 当数据。
|
|
77
|
+
- 出错时按 `error.kind` 分支,不要按 `code`(见 errors.md)。
|
|
78
|
+
- 退出码:`0` 成功 · `1` 业务错误 · `2` 用法错误 · `3` 网络错误 · `4` 需要人工确认。
|
|
79
|
+
|
|
80
|
+
## 其余五份协议(按需阅读)
|
|
81
|
+
|
|
82
|
+
- [protocols.md](protocols.md)——数据可信度:下结论前看什么、0 行怎么解读、单位与时间怎么核对。
|
|
83
|
+
- [metrics.md](metrics.md)——指标语义:三处「行数 ≠ 实体数」。
|
|
84
|
+
- [errors.md](errors.md)——错误处理:按 kind 分支的动作表。
|
|
85
|
+
- [forbidden.md](forbidden.md)——禁止事项。
|
|
86
|
+
- [setup.md](setup.md)——需要人工配置的机器人编号等 ID。
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
# 错误处理协议
|
|
2
|
+
|
|
3
|
+
失败时 stdout 是 `{"ok":false,"error":{code,kind,retryable,message,hint?}}`。
|
|
4
|
+
**按 `kind` 分支,不要按 `code` 分支**——`code` 可能是服务端的数字码,也可能是 CLI 合成的词,
|
|
5
|
+
查不到统一的错误码表;`kind` 才是 CLI 承诺的闭集。
|
|
6
|
+
|
|
7
|
+
退出码:`0` 成功 · `1` 业务错误 · `2` 用法错误 · `3` 网络错误 · `4` 需要人工确认。
|
|
8
|
+
|
|
9
|
+
## kind → 动作
|
|
10
|
+
|
|
11
|
+
| 信号 | 动作 |
|
|
12
|
+
|---|---|
|
|
13
|
+
| `kind: auth_missing` | 凭证未配置(环境变量与配置文件都没有)。按 hint 设置 `QIYU_APP_KEY`/`QIYU_APP_SECRET` 或让人类跑 `qiyu auth login`;原命令重试无用 |
|
|
14
|
+
| `kind: config_insecure` | 配置文件**含凭证**但权限过宽(group/other 可读到 appSecret)。重试无用——转告人类执行 hint 里点名的 `chmod` 后重跑 |
|
|
15
|
+
| `kind: auth` | 凭证被服务端拒绝(key 错、IP 不在白名单、接口无权限)。按 hint 修配置;重试无用 |
|
|
16
|
+
| `kind: bad_time` | 时间戳超期。CLI 已自动重签重试过;仍失败说明本机时钟真的偏了——校准系统时间 |
|
|
17
|
+
| `kind: param` | 参数错误。按 message 与 hint 修正;重试无用 |
|
|
18
|
+
| `kind: usage` | 调用方式有误(退出码 2)。改命令或参数重来;原样重试毫无意义 |
|
|
19
|
+
| `kind: rate_limit` | 限流。看 `retry_after`:`source` 为 `fallback` 表示该秒数是保守兜底、不是实测冷却(睡完可能再吃一次限流);秒数超过 60 就不要干等——转本地查询通道先做别的分析,稍后再回来。若错误里带 `retry_strategy: switch_to_local` 与 `fallback` 命令,说明**该接口在同步任务里有本地表映射、且配置指向的库文件存在**——CLI 只检查了这两件事,**没有打开库、没有确认那张表真的存在**(把库路径指向别的文件时这条建议照样会出现),所以先跑 `qiyu db tables` 确认表在清单里。即便在,那也只是**整表数据源,不是这次请求的等价替代**:它不会带上你 body 里的筛选条件(时间窗/状态/关键字等),要自己补 WHERE(`--sql` 或 `--since`/`--until`);表存在也不等于已同步或覆盖你要的时间窗,先按 `hint` 用 `qiyu db tables` / `qiyu sync status` 确认行数与水位再采信 |
|
|
20
|
+
| `kind: window_too_large` | 时间跨度超限。上限天数看报文里的数字(如「> 31」即 31 天),或查 `qiyu api list` 输出里该接口的 `max_window_days`;按它切片、分批请求 |
|
|
21
|
+
| `kind: window_misaligned` | 时间边界没对齐自然日(结束边界不得晚于今天零点)。切片修不好——把边界对齐到自然日再试 |
|
|
22
|
+
| `kind: module_offline` | 模块未开通。永久失败,找人类开通,不要重试 |
|
|
23
|
+
| `kind: not_in_queue` | 业务状态,不是故障。按业务语义处理,不重试 |
|
|
24
|
+
| `kind: pending` | 异步任务未完成(如会话导出轮询)。这是正常中间态——稍后再次轮询,不要判成失败 |
|
|
25
|
+
| `kind: route_not_found` | 服务端没有这条路由。接口 id 写错,或 CLI 的接口注册表有误;重试无用,报告人类 |
|
|
26
|
+
| `kind: internal` | 看 `retryable`:true 才退避重试;false 时按 message 的两种已知成因查参数(无效参数、翻页越界),重试无用 |
|
|
27
|
+
| `kind: network` | 网络层故障(退出码 3)。检查网络后退避重试 |
|
|
28
|
+
| `kind: unknown` | 未分类错误。按 message 判断,不要盲目重试 |
|
|
29
|
+
| `kind: needs_confirmation` | 危险操作等待确认(退出码 4)。**停下**,向人类复述该操作及其目标;**绝不自动追加 `--yes`** |
|
|
30
|
+
| `kind: store_locked` | 本地库正被写进程持锁(例如同步进行中)。退避后重试;期间可以先用已有数据做分析 |
|
|
31
|
+
| `kind: store_not_initialized` | 本地库不可用(不存在 / 缺表 / 不是本 CLI 的库 / 依赖未安装)。**按 `hint` 行动**:只有 hint 指向 `qiyu store init` 时才跑它,再跑 `qiyu sync run`;其余成因换 `--db` 路径或按 hint 安装依赖,原样重跑 `store init` 无效 |
|
|
32
|
+
| `kind: query_timeout` | 查询超时。缩小时间窗口、减少分组列或降低 `--limit` 后重试 |
|
|
33
|
+
| `kind: sync_not_run` | 还没有成功同步过。这个 kind **只由 `sync install` 的前置探测产出**(`sync status` 不产出它,水位全为 null 时按 `SKILL.md` 的开场协议处理):先跑一次 `qiyu sync run` 让至少一个任务真正同步成功,再装调度 |
|
|
34
|
+
|
|
35
|
+
## 退出码 4 的信号
|
|
36
|
+
|
|
37
|
+
退出码 4 **一定**同时携带 `confirm_required`、`confirm_arg`、`risk` 与 `target`,且
|
|
38
|
+
`retryable` 为 false。收到它时:
|
|
39
|
+
|
|
40
|
+
1. 向人类复述:哪个接口、目标对象是什么、为什么不可逆。
|
|
41
|
+
2. 等人类明确同意后,由人类决定是否加 `--yes` 重跑;**不要自己补**。
|
|
42
|
+
3. 人类拒绝时,按业务语义收尾(例如改为查询现状),不要换个接口绕过闸门。
|
|
43
|
+
|
|
44
|
+
## 歧义信号(尚未启用)
|
|
45
|
+
|
|
46
|
+
名称解析(G2)交付后会引入一个「候选不止一个」的信号,名字是 ambiguous。
|
|
47
|
+
|
|
48
|
+
- **当前版本不会产出它**——不要为它写分支,也不要假装见过它。
|
|
49
|
+
- 它启用后:把候选列表原样交给人类,**不得自行选择**(猜错会把人派错、把工单改错)。
|
|
50
|
+
- 在那之前,涉及人名、组名解析的需求直接问人类。
|
|
51
|
+
|
|
52
|
+
## 重试总则
|
|
53
|
+
|
|
54
|
+
只在 `retryable` 为 true、且动作本身安全(只读或幂等)时退避重试;`needs_confirmation`、
|
|
55
|
+
`usage`、`param`、`auth` 类错误重试是浪费,危险操作重试是事故。
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
# 禁止事项
|
|
2
|
+
|
|
3
|
+
这些禁令每一条都对应一类真实事故:静默失败、重复执行、数据泄露或把不成熟的能力当工具。
|
|
4
|
+
|
|
5
|
+
## 1. 不要读配置文件
|
|
6
|
+
|
|
7
|
+
`~/.config/qiyu/config.json` 属于人类维护面:凭证与存储行为都由它(或环境变量)决定,
|
|
8
|
+
CLI 对未知键 fail-closed 校验。**G1 起文件里可能含凭证**(`auth login` 会写入
|
|
9
|
+
`profiles.<name>.credentials`)——读它的风险从"越权"升到了"拿到机密"。
|
|
10
|
+
读它没有收益——它决定的一切都能用命令与 flag 自描述获得:
|
|
11
|
+
需要知道库路径与后端时用 `qiyu store status`(它的输出里**不含 profile**)。profile 与
|
|
12
|
+
`--db` / `--backend` 一样是定位参数:给名字,交给命令自己解析成实际的库路径与后端。
|
|
13
|
+
需要知道凭证状态时用 `qiyu auth whoami`。不要 cat、grep 或解析该文件,也不要把它的内容
|
|
14
|
+
写进任何输出或日志。
|
|
15
|
+
|
|
16
|
+
## 2. 不需要 `--pretty`
|
|
17
|
+
|
|
18
|
+
默认输出已是紧凑、可解析的 JSON(一行、stdout)——按 JSON 解析即可,缩进格式是给人看的,
|
|
19
|
+
对 Agent 没有增益。不要把 `--pretty` 写进你生成的命令示例;正常调用保持不带它。
|
|
20
|
+
|
|
21
|
+
## 3. 不要盲目重试
|
|
22
|
+
|
|
23
|
+
按 `errors.md` 的 kind 表决定动不动作:
|
|
24
|
+
|
|
25
|
+
- `retryable: false` 的错误(参数错、权限、用法错、需要确认)重试是浪费——先修成因。
|
|
26
|
+
- 危险操作(写接口)重试可能重复执行——没有人类明确同意,绝不重试。
|
|
27
|
+
- 退避重试时用有限次数与递增间隔;循环撞限流只会让冷却更长。
|
|
28
|
+
|
|
29
|
+
## 4. 不要拿 `--sql` 跑单表简单过滤
|
|
30
|
+
|
|
31
|
+
`qiyu query --table <表>` 是单表查询的**默认通道**:表名闭集校验、时间过滤、分组计数、
|
|
32
|
+
按列声明的精确脱敏。`qiyu query --sql <SQL>` 是给 JOIN、跨表聚合等受约束通道表达不了的场景的。
|
|
33
|
+
|
|
34
|
+
用 `--sql` 跑 `--table` 能表达的查询,等于自己放弃列白名单与精确脱敏——多读出的敏感列
|
|
35
|
+
会直接进你的上下文与日志。判断标准:如果查询只需要一张表加过滤/分组,用 `--table`。
|
|
36
|
+
|
|
37
|
+
## 5. 不要在确认新鲜度前下结论
|
|
38
|
+
|
|
39
|
+
先看 `qiyu sync status` 的水位与覆盖区间,再看查询 meta 的 `resolved_range` 与
|
|
40
|
+
`data_coverage`;两者对不上时(例如报表截止昨天而任务水位停在前天)如实说明。
|
|
41
|
+
没有新鲜度证据的结论,在人类眼里就是「可能是旧数据」——与其被追问,不如一开始就写清。
|
|
42
|
+
|
|
43
|
+
## 6. 其他硬性红线
|
|
44
|
+
|
|
45
|
+
- **不要猜测表名、列名、接口 id**:一律 `qiyu db tables` / `qiyu db describe <表>` /
|
|
46
|
+
`qiyu api list` 先查。名字是闭集,猜错的代价是静默失败。
|
|
47
|
+
- **不要关闭脱敏后把输出写进日志或对外报表**:`--no-mask` 只用于人类明确要求的临时排查,
|
|
48
|
+
输出不得落盘、不得转发。
|
|
49
|
+
- **不要缓存或复用会话类实时接口的动态标识**:它们会自行轮换,缓存后继续用只会失败。
|
|
50
|
+
- **不要为绕过闸门换接口**:确认闸门按接口注册,绕行(换写法、换参数形态)是对闸门的否定,
|
|
51
|
+
一律视为违规操作。
|
|
52
|
+
- **不要把 stderr 当数据**:进度与日志走 stderr,数据只在 stdout 的 JSON 里。
|
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
# 指标语义协议
|
|
2
|
+
|
|
3
|
+
原始行数不等于业务实体数。以下三处如果直接把行数当答案,结果会**系统性偏高**,
|
|
4
|
+
而且不会报任何错。回答前先声明你用的是哪种语义;两种都要时分开报。
|
|
5
|
+
|
|
6
|
+
具体计数不要凭记忆——交给运行时:
|
|
7
|
+
|
|
8
|
+
```
|
|
9
|
+
qiyu db tables
|
|
10
|
+
qiyu sync tasks
|
|
11
|
+
qiyu query --table <表>
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
## 1. 知识库条目:知识点 vs 相似问
|
|
15
|
+
|
|
16
|
+
知识库条目数据集里混着两类行:
|
|
17
|
+
|
|
18
|
+
- **知识点行**:一个标准问题加一个答案,是「一个知识点」。
|
|
19
|
+
- **相似问行**:挂在某个知识点下的近似问法,**不携带答案**,只是同一知识点的另一种说法。
|
|
20
|
+
它们与所属知识点共享同一个分组标识。
|
|
21
|
+
|
|
22
|
+
所以「有多少个知识点?」不能答条目数据集的原始行数——那会把相似问全算成独立知识点。
|
|
23
|
+
正确语义是**按分组标识去重后的数量**(等价于知识点行的数量)。如果人类确实要把相似问也算进去,
|
|
24
|
+
在结论里显式写明「含相似问,共 N 条问法」。
|
|
25
|
+
|
|
26
|
+
先跑一次按分组计数的查询确认口径,再回答;不要用「总行数 ÷ 2」之类的经验值。
|
|
27
|
+
|
|
28
|
+
## 2. 会话:人工会话 vs 机器人会话
|
|
29
|
+
|
|
30
|
+
会话数据集包含**机器人会话**,且机器人侧的很多字段恒为空(没有人工处理人、没有人工类目等)。
|
|
31
|
+
直接对全部会话聚合,会把机器人的量混进「人工客服工作量」,并且稀释类目分布。
|
|
32
|
+
|
|
33
|
+
- 会话类型是本地同步时按处理人编号派生出来的确定性列,不是上游字段。
|
|
34
|
+
- **报告人工客服工作量前必须按会话类型过滤**,排除机器人会话;报告「总咨询量」时可以说全量,
|
|
35
|
+
但要写明含机器人。
|
|
36
|
+
- 机器人会话里处理人编号与机器人编号之间存在固定的符号关系(负数),可用于反推机器人编号,
|
|
37
|
+
见 setup.md。
|
|
38
|
+
- 无效会话是哨兵值,不是类目:计算任何问题分布前必须排除,且哨兵的字面量是中文——按英文匹配
|
|
39
|
+
一个都排除不掉。
|
|
40
|
+
|
|
41
|
+
## 3. 工单工作量:工单数 vs 日志条数
|
|
42
|
+
|
|
43
|
+
工单的操作日志按「动作」逐条记录:一个人连续改 8 个字段就是 8 条日志,关一次单可能产生多条
|
|
44
|
+
关闭记录。所以「张三昨天处理了多少工单」的正确语义是**不同的工单数**,不是日志条数。
|
|
45
|
+
|
|
46
|
+
另外两件事会扭曲这个指标:
|
|
47
|
+
|
|
48
|
+
- **系统操作会混进来**:自动流转、自动关闭以系统账号身份记日志;不排除系统账号,
|
|
49
|
+
它会在排行榜上常年霸榜。
|
|
50
|
+
- **自然日按上海时区算**:UTC 容器里的「昨天」会差 8 小时,且不会报错。
|
|
51
|
+
|
|
52
|
+
## 4. 知识库还有一处语义分叉:并集 vs 隔离
|
|
53
|
+
|
|
54
|
+
条目数据集是**跨全部机器人的并集**,而分类树是**按机器人隔离**的。因此:
|
|
55
|
+
|
|
56
|
+
- 「某个机器人有哪些知识分类」——查该机器人的分类树,**不要**从条目数据集的分类字段反推
|
|
57
|
+
(那会把别的机器人的分类混进来)。
|
|
58
|
+
- 条目数据集里机器人编号是承重字段:按机器人切片先按它过滤。
|
|
59
|
+
|
|
60
|
+
## 5. 通用做法
|
|
61
|
+
|
|
62
|
+
1. 先声明语义:「按知识点去重」还是「原始行数」、「人工会话」还是「含机器人」。
|
|
63
|
+
2. 用 `qiyu query --table <表>` 的 `--group-by` 做分组计数,让命令给出分组后的数,而不是自己拿
|
|
64
|
+
行数做除法。
|
|
65
|
+
3. 结论里同时写出语义、时间窗口与数据覆盖区间——三者缺一,数字就不可复核。
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
# 数据可信度协议
|
|
2
|
+
|
|
3
|
+
本地库与实时 API 是两个数据面,任何「有多少、什么时候、对不对」的回答都要先经过本协议。
|
|
4
|
+
核心原则:**下结论之前,证据链必须闭环**——哪个命令、哪个窗口、哪个过滤条件,缺一不可。
|
|
5
|
+
|
|
6
|
+
## 1. 下结论前先看 meta
|
|
7
|
+
|
|
8
|
+
`qiyu query` 的输出自带 meta,至少检查这几项再说话:
|
|
9
|
+
|
|
10
|
+
- `rows` / `limit_applied` / `truncated`:`truncated` 为 true 表示只拿到截断样本——放宽
|
|
11
|
+
`--limit` 或缩小时间窗口重查,不要拿样本当全量。
|
|
12
|
+
- `warnings`:非空必须逐条读。它们点名「窗口内部有缺口」「区间天数不足」这类**静默失败**;
|
|
13
|
+
忽略 warnings 的 Agent 会把残缺数据当事实汇报。
|
|
14
|
+
- `masked` / `masked_columns` / `mask_warnings`:输出默认脱敏;`mask_warnings` 非空说明
|
|
15
|
+
脱敏可能不完整,含敏感列的结论要额外小心。
|
|
16
|
+
- `resolved_range` / `data_coverage`:命令实际生效的时间区间、本地数据的实际覆盖范围。
|
|
17
|
+
报告结论时带上这两个区间,让人类知道你算的是哪段数据。
|
|
18
|
+
- `--sql` 通道不判定区间与覆盖:`resolved_range` 与 `data_coverage` **恒为 null**——实际
|
|
19
|
+
区间以你写的 SQL 过滤为准,报告时自己写清。
|
|
20
|
+
|
|
21
|
+
## 2. 0 行 ≠ 没有数据
|
|
22
|
+
|
|
23
|
+
0 行是比报错危险的失败模式——错误处理不会触发,你会直接汇报「没有数据」。0 行至少有三种成因:
|
|
24
|
+
|
|
25
|
+
1. **窗口写错**:相对时间按上海时区解析,而 Agent 常跑在 UTC 容器里——「昨天」可能不是
|
|
26
|
+
人类说的昨天,且不会报任何错。
|
|
27
|
+
2. **本地还没同步到这段**:用 `qiyu sync status` 看水位与缺口;`qiyu sync verify` 可以核对
|
|
28
|
+
本地与远端的一致性(发现漂移时以非零退出码明示)。
|
|
29
|
+
3. **真的没有数据**。
|
|
30
|
+
|
|
31
|
+
报告 0 行时写「查询窗口 X 到 Y 内 0 行」,并说明排除了哪几种成因;不要写「系统里没有」。
|
|
32
|
+
|
|
33
|
+
## 3. 单位用 stats fields 核对
|
|
34
|
+
|
|
35
|
+
- **绝不猜单位**——百分比还是绝对值、按日还是按小时,猜错数字全错。报表字段的声明单位、
|
|
36
|
+
本地观测分布、哨兵值由 `qiyu stats fields <报表表>` 给出。
|
|
37
|
+
- 哨兵值会混进聚合(例如「无处理人」用特殊编号表示,不排除就会凭空多出一个「员工」)。
|
|
38
|
+
先看观测分布,再决定过滤条件。
|
|
39
|
+
- 声明了但本地观测不到取值的字段,报告时写「未观测到取值」——声明是契约,不是事实。
|
|
40
|
+
|
|
41
|
+
## 4. 时间一律用绝对日期
|
|
42
|
+
|
|
43
|
+
- 结论里写绝对日期(如 2026-10-20),不写「昨天」「上周」——相对词在不同时区下指向不同的日子。
|
|
44
|
+
- 命令的 `--since` / `--until` 接受绝对日期与 ISO 8601。**只给 `--since` 时上界是当前时刻**
|
|
45
|
+
(含今天已同步的数据);今天的日报行通常次日才落库,所以区间尾部常为空——以
|
|
46
|
+
`resolved_range` / `data_coverage` 判断实际覆盖。要把窗口止于某个自然日,显式给 `--until`
|
|
47
|
+
(日期型列含该日全天;时刻型列请写清时刻,裸日期会被当成当天零点)。
|
|
48
|
+
- 所有相对时间按上海时区解析;响应里的 `resolved_range` 是实际生效的区间——引用它,不要复述
|
|
49
|
+
你自己的输入。
|
|
50
|
+
|
|
51
|
+
## 5. 结论要带出处
|
|
52
|
+
|
|
53
|
+
- 每个数字都能指回一条命令与一个窗口;指不回来的数字不要写进结论。
|
|
54
|
+
- 推断与观测分开写:推断要标注「推断」,不要包装成观测结果。
|
|
55
|
+
- 不确定就说不确定。对数据任务,一个带不确定性的诚实结论远好过一个干净的错误结论。
|