@giftsofprometheus/cli 0.3.0 → 0.5.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/README.md CHANGED
@@ -37,6 +37,7 @@ giftsofprometheus doctor
37
37
  ## Быстрый старт
38
38
 
39
39
  ```bash
40
+ giftsofprometheus ask 'как оценивать агентов' --q 'agent evaluation' # фрагменты транскриптов
40
41
  giftsofprometheus talks search 'оценка агентов' # без аккаунта
41
42
  giftsofprometheus talks get <slug> # описание, спикеры, темы, ссылка на видео
42
43
 
@@ -112,10 +113,11 @@ npx skills add timurkhakhalev/giftsofprometheus-cli
112
113
 
113
114
  | Команда | Что делает | Аккаунт |
114
115
  |---|---|---|
116
+ | `ask <вопрос> [--q формулировка] [--limit n] [--per-talk n]` | Фрагменты транскриптов с цитатами и ссылками на секунду; `--q` повторяется до двух раз | ✓ |
115
117
  | `talks search <запрос> [--page n]` | Поиск опубликованных докладов по названию, описанию, спикеру и теме | |
116
118
  | `talks list [--page n]` | Каталог по страницам | |
117
119
  | `talks get <slug-или-id>` | Доклад с описанием, спикерами, темами и видео | |
118
- | `talks content <slug-или-id>` | Полный транскрипт на языке доклада | ✓ |
120
+ | `talks content <slug-или-id> [--rec-id UUID]` | Полный транскрипт на языке доклада | ✓ |
119
121
  | `favorites list [--page n] [--limit n]` | Ваше избранное | ✓ |
120
122
  | `favorites add <slug-или-id>` / `remove` | Добавить в избранное или убрать | ✓ |
121
123
  | `profile get` | Ваши интересы и текущая задача | ✓ |
package/dist/index.js CHANGED
@@ -3,12 +3,12 @@ import { z } from 'zod';
3
3
  import { Command } from 'commander';
4
4
  import { chmod, lstat, mkdir, readFile, realpath, rename, stat, writeFile, unlink } from 'node:fs/promises';
5
5
  import { homedir } from 'node:os';
6
- import { isAbsolute, join } from 'node:path';
6
+ import { basename, isAbsolute, join, resolve } from 'node:path';
7
7
  import { spawn } from 'node:child_process';
8
8
  import { randomUUID } from 'node:crypto';
9
9
  import { createRequire } from 'node:module';
10
10
  import { fileURLToPath } from 'node:url';
11
- import { mergeSkill, newerVersion, skillHash } from './skill-files.js';
11
+ import { mergeSkill, newerVersion, personalDescription, skillDescription, skillHash, tailTopics } from './skill-files.js';
12
12
  const { version } = z.object({ version: z.string() }).parse(createRequire(import.meta.url)('../package.json'));
13
13
  const program = new Command();
14
14
  const base = (process.env.GIFTSOFPROMETHEUS_URL || 'https://giftsofprometheus.com').replace(/\/$/, '');
@@ -456,6 +456,29 @@ program
456
456
  nextStep: !reachable ? 'Check GIFTSOFPROMETHEUS_URL and server availability' : !authenticated ? 'Run giftsofprometheus login' : null,
457
457
  };
458
458
  }));
459
+ program
460
+ .command('ask')
461
+ .description('Find relevant passages in talk transcripts')
462
+ .argument('<query>', 'question or search formulation')
463
+ .option('--q <query>', 'another formulation, up to three in total', (value, previous) => [...previous, value], [])
464
+ .option('--limit <n>', 'maximum number of talks')
465
+ .option('--per-talk <n>', 'maximum passages per talk')
466
+ .action(run((query, options) => {
467
+ const queries = z
468
+ .array(z.string().trim().min(1).max(200))
469
+ .min(1)
470
+ .max(3)
471
+ .parse([query, ...options.q]);
472
+ const number = z.string().regex(/^\d+$/);
473
+ const params = new URLSearchParams();
474
+ for (const value of queries)
475
+ params.append('q', value);
476
+ if (options.limit !== undefined)
477
+ params.set('limit', number.parse(options.limit));
478
+ if (options.perTalk !== undefined)
479
+ params.set('perTalk', number.parse(options.perTalk));
480
+ return request(`/api/knowledge/passages?${params}`);
481
+ }));
459
482
  const talks = program.command('talks').description('Browse talks');
460
483
  talks
461
484
  .command('list')
@@ -465,7 +488,7 @@ talks
465
488
  .command('search')
466
489
  .argument('<query>')
467
490
  .option('--page <page>', 'page number', '1')
468
- .action(run((query, options) => request(`/api/knowledge/talks?q=${encodeURIComponent(query)}&page=${encodeURIComponent(options.page)}`, 'GET', undefined, false)));
491
+ .action(run((query, options) => request(`/api/knowledge/talks?q=${encodeURIComponent(query)}&page=${encodeURIComponent(options.page)}`)));
469
492
  // The command a person typed, so a hint can be pasted back as is
470
493
  const launcher = /[\\/]_npx[\\/]/.test(packageRoot) ? 'npx @giftsofprometheus/cli' : 'giftsofprometheus';
471
494
  talks
@@ -483,8 +506,9 @@ talks
483
506
  .argument('<slug-or-id>')
484
507
  .option('--rec-id <recId>', 'recId of the list the talk came from (feed, search or similar)')
485
508
  .action(run(async (id, options) => {
509
+ const query = recIdQuery(options.recId);
486
510
  const talk = await resolveTalk(id);
487
- const result = await request(`/api/knowledge/talks/${encodeURIComponent(String(talk.slug))}/content${recIdQuery(options.recId)}`, 'POST');
511
+ const result = await request(`/api/knowledge/talks/${encodeURIComponent(String(talk.slug))}/content${query}`, 'POST');
488
512
  // After the transcript: talks like this one, or saving it if the user found it useful
489
513
  console.error(`Next: similar talks — ${launcher} talks similar ${talk.slug}; save it if the user asks — ${launcher} favorites add ${talk.slug}`);
490
514
  return result;
@@ -503,6 +527,17 @@ talks
503
527
  console.error(`Next: open one with ${launcher} talks content <slug> --rec-id ${result.recId}`);
504
528
  return result;
505
529
  }));
530
+ const reactionTypes = { like: 'like', dislike: 'dislike', 'not-interested': 'not_interested', clear: 'clear_reaction' };
531
+ talks
532
+ .command('react')
533
+ .description('Record what the user said about a talk: like, dislike, not-interested or clear')
534
+ .argument('<slug-or-id>')
535
+ .argument('<reaction>', Object.keys(reactionTypes).join(' | '))
536
+ .option('--rec-id <recId>', 'recId of the list the talk came from')
537
+ .action(run(async (id, reaction, options) => {
538
+ const type = z.enum(['like', 'dislike', 'not-interested', 'clear']).parse(reaction);
539
+ return event(id, reactionTypes[type], options.recId);
540
+ }));
506
541
  const favorites = program.command('favorites').description('Manage bookmarks');
507
542
  favorites
508
543
  .command('list')
@@ -683,6 +718,69 @@ skill
683
718
  .description('Replace installed copies of the skill that are older than this CLI; a custom description is kept')
684
719
  .option('--force', 'also replace copies that were edited by hand')
685
720
  .action(run((options) => updateSkills(Boolean(options.force))));
721
+ const profileTopics = z.object({
722
+ interests: z.array(z.object({ topic: z.string().optional(), level: z.enum(['high', 'interested', 'not_interested']) })),
723
+ topics: z.array(z.object({ slug: z.string(), title: z.string(), section: z.string().nullable() })),
724
+ });
725
+ /** Titles of the user's topics for the skill tail: strong interests first, subtopics before whole sections */
726
+ async function personalTopics() {
727
+ const profile = profileTopics.parse(await request('/api/knowledge/profile'));
728
+ const bySlug = new Map(profile.topics.map(t => [t.slug, t]));
729
+ return profile.interests
730
+ .flatMap(i => {
731
+ const topic = i.topic === undefined ? undefined : bySlug.get(i.topic);
732
+ return topic && i.level !== 'not_interested' ? [{ title: topic.title, order: (i.level === 'high' ? 0 : 2) + (topic.section ? 0 : 1) }] : [];
733
+ })
734
+ .sort((a, b) => a.order - b.order)
735
+ .map(t => t.title);
736
+ }
737
+ // A command the user can paste into their own terminal, where the file may be writable
738
+ const shellQuote = (value) => `'${value.replaceAll("'", `'\\''`)}'`;
739
+ /**
740
+ * Adds the user's topics to the description of the skill copy the agent loaded, so the agent reaches for it on them too.
741
+ * Only a SKILL.md of this skill is changed; a copy that cannot be written is reported with a command for the user.
742
+ */
743
+ async function personalizeSkill(o) {
744
+ const given = resolve(o.file);
745
+ const file = basename(given) === 'SKILL.md' ? given : join(given, 'SKILL.md');
746
+ let text;
747
+ try {
748
+ text = await readFile(file, 'utf8');
749
+ }
750
+ catch {
751
+ throw new ApiError(`No skill file at ${file}`);
752
+ }
753
+ if (!/^---\r?\nname: giftsofprometheus\r?\n/.test(text))
754
+ throw new ApiError(`${file} is not the giftsofprometheus skill`);
755
+ const line = skillDescription(text);
756
+ if (!line)
757
+ throw new ApiError(`${file} has no description line`);
758
+ const topics = tailTopics(await personalTopics());
759
+ const next = personalDescription(line, topics);
760
+ if (next === line)
761
+ return { personalized: true, changed: false, path: file, topics };
762
+ const temporary = `${file}.${randomUUID()}.tmp`;
763
+ try {
764
+ await writeFile(temporary, text.replace(/\r\n/g, '\n').replace(line, () => next), { mode: (await stat(file)).mode & 0o777, flag: 'wx' });
765
+ await rename(temporary, file);
766
+ }
767
+ catch (e) {
768
+ await unlink(temporary).catch(() => { });
769
+ return {
770
+ personalized: false,
771
+ path: file,
772
+ topics,
773
+ reason: e instanceof Error ? e.message : 'Write failed',
774
+ command: `${launcher} skill personalize --file ${shellQuote(file)}`,
775
+ };
776
+ }
777
+ return { personalized: true, changed: true, path: file, topics };
778
+ }
779
+ skill
780
+ .command('personalize')
781
+ .description("Add the user's topics (ten words at most) to the description of the skill copy at --file; requires login")
782
+ .requiredOption('--file <path>', 'SKILL.md of the loaded skill, or its folder')
783
+ .action(run(personalizeSkill));
686
784
  // The daily check runs after the command, so it never delays or breaks its output; doctor and skill report the same state themselves
687
785
  let skipNotice = false;
688
786
  program.hook('preAction', (_, action) => {
@@ -15,12 +15,20 @@ export function skillHash(text) {
15
15
  .trim();
16
16
  return createHash('sha256').update(body).digest('hex').slice(0, 16);
17
17
  }
18
- /** The bundled skill with the installed description kept, unless that description is one the CLI shipped */
18
+ /**
19
+ * The bundled skill with the installed description kept, unless that description is one the CLI shipped.
20
+ * A shipped description with a personal tail becomes the new shipped description with the same tail.
21
+ */
19
22
  export function mergeSkill(bundled, installed, stockDescriptions) {
20
23
  const own = skillDescription(installed);
21
- if (!own || stockDescriptions.includes(own))
24
+ const text = bundled.replace(/\r\n/g, '\n');
25
+ if (!own)
22
26
  return bundled;
23
- return bundled.replace(/\r\n/g, '\n').replace(DESCRIPTION, () => own);
27
+ if (stockDescriptions.includes(baseDescription(own))) {
28
+ const fresh = skillDescription(text);
29
+ return fresh ? text.replace(DESCRIPTION, () => `${fresh}${personalTail(own)}`) : bundled;
30
+ }
31
+ return text.replace(DESCRIPTION, () => own);
24
32
  }
25
33
  export function newerVersion(latest, current) {
26
34
  const parse = (value) => value.split('-')[0]?.split('.').map(Number) ?? [];
@@ -34,3 +42,36 @@ export function newerVersion(latest, current) {
34
42
  }
35
43
  return false;
36
44
  }
45
+ // A personal tail: up to ten words in all, naming the user's topics, so the agent also reaches for the skill on them
46
+ const TAIL_PREFIX = ' Also good for ';
47
+ const TAIL = / Also good for [^\n]*$/;
48
+ const TAIL_WORDS = 10;
49
+ /** Topic titles that fit the tail, in the given order; characters YAML or the line could trip on are dropped */
50
+ export function tailTopics(titles) {
51
+ const chosen = [];
52
+ let words = TAIL_PREFIX.trim().split(/\s+/).length;
53
+ for (const raw of titles) {
54
+ const title = raw
55
+ .replace(/[:#"'`\n\r;]/g, ' ')
56
+ .replace(/\s+/g, ' ')
57
+ .trim();
58
+ const count = title ? title.split(' ').length : 0;
59
+ if (!count || chosen.includes(title) || words + count > TAIL_WORDS)
60
+ continue;
61
+ chosen.push(title);
62
+ words += count;
63
+ }
64
+ return chosen;
65
+ }
66
+ /** The description line without a personal tail */
67
+ export function baseDescription(line) {
68
+ return line.replace(TAIL, '');
69
+ }
70
+ /** The description line with a tail for these topics, or without one when there are none */
71
+ export function personalDescription(line, topics) {
72
+ const base = baseDescription(line);
73
+ return topics.length ? `${base}${TAIL_PREFIX}${topics.join('; ')}.` : base;
74
+ }
75
+ export function personalTail(line) {
76
+ return line.match(TAIL)?.[0] ?? '';
77
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@giftsofprometheus/cli",
3
- "version": "0.3.0",
3
+ "version": "0.5.0",
4
4
  "description": "Search AI conference talks, read transcripts, and manage your Gifts of Prometheus favorites from the shell or an AI agent",
5
5
  "keywords": [
6
6
  "agents",
@@ -18,7 +18,7 @@ Run `command -v giftsofprometheus`. If it is missing, run every command below as
18
18
 
19
19
  ## Sign in
20
20
 
21
- Do not stop the task to send the user to the terminal. When a command needs an account (transcripts, favorites, profile, feed, `onboarding finish`) or fails with status 401:
21
+ Do not stop the task to send the user to the terminal. When a command needs an account (passage search, transcripts, favorites, profile, feed, `onboarding finish`) or fails with status 401:
22
22
 
23
23
  1. Run `giftsofprometheus --json login --start`. It returns `verificationUrl` and `userCode` at once and tries to open the browser.
24
24
  2. Tell the user in one line to open the link and confirm the code.
@@ -30,6 +30,7 @@ The CLI stores its session outside the project. Never print, copy or ask for it.
30
30
  ## Read
31
31
 
32
32
  ```bash
33
+ giftsofprometheus --json ask 'how to evaluate agents' --q 'agent evaluation' --q '智能体评估' # passages, requires login
33
34
  giftsofprometheus --json talks search 'agent evaluation' # published talks by title, summary, speaker or topic
34
35
  giftsofprometheus --json talks list --page 2 # the whole catalog, page by page
35
36
  giftsofprometheus --json talks get <slug-or-id> # one talk: summary, speakers, topics, publication
@@ -40,12 +41,15 @@ giftsofprometheus --json favorites list # saved talks, requir
40
41
  giftsofprometheus --json profile get # interests and current task, requires login
41
42
  ```
42
43
 
44
+ - For questions about what speakers say, use `ask` with 2–3 formulations: English, Chinese and the original language. For names, titles, topics and conferences use `talks search`.
45
+ - Open a found transcript with `talks content <slug> --rec-id <recId>` from the `ask` response. Summarize positions of different speakers and give the passage `url` links with timecodes.
46
+ - If `ask` returns 503, try later or use `talks search`.
43
47
  - Lists are paginated: check `totalPages` and pass `--page`.
44
48
  - Search and use the returned `slug` or `id` for exact reads.
45
49
  - A transcript is in the talk's original language. Segment timecodes are in milliseconds from the start of the talk. When a talk is a part of a longer recording, `sourceRange` gives its bounds in that recording. A talk without a transcript returns an empty array.
46
50
  - `request <path>` makes a read-only GET to a path under `/api/knowledge/` or `/api/account/` that no command covers.
47
51
  - Reading never needs the user's confirmation: search, open talks and transcripts as the task requires.
48
- - A list with a `recId` (feed, search, similar) puts it into each item's `contentUrl`. When you open a talk from that list, pass it on: `talks content <slug> --rec-id <recId>`, and `favorites add <slug> --rec-id <recId>` when the user saves it.
52
+ - A list with a `recId` (feed, search, similar, `ask`) returns it at the top of the response. When you open a talk from that list, pass it on: `talks content <slug> --rec-id <recId>`, and `favorites add <slug> --rec-id <recId>` when the user saves it.
49
53
 
50
54
  ## Next steps
51
55
 
@@ -57,6 +61,25 @@ After answering, offer one next step in a short line, matched to where the user
57
61
 
58
62
  Commands print the suggested next command on stderr. It is a hint for you; do not run a change without the user.
59
63
 
64
+ ## Feedback
65
+
66
+ Once per conversation, when the user is signed in and you opened two or more transcripts for them (from any list, including `ask`), ask in one message how the talks landed, as a natural continuation: "Of these, which hit the mark and which missed?" with the titles as a short numbered list. Ask when their question is answered, not in the middle of their work, and never again in the same conversation.
67
+
68
+ Record only what the user said, one command per talk, with the `recId` of the list the talk came from:
69
+
70
+ ```bash
71
+ giftsofprometheus --json talks react <slug-or-id> like|dislike|not-interested|clear --rec-id <recId>
72
+ ```
73
+
74
+ "Useful", "great" → `like`; "missed", "too basic" → `dislike`; "not my topic" → `not-interested`; talks they did not mention stay unjudged. Then say in one line that the feed takes it into account. If they ignore the question, drop it.
75
+
76
+ ## Personal topics
77
+
78
+ After `onboarding finish` or a `profile update` that changed interests, run `giftsofprometheus --json skill personalize --file <path of this SKILL.md>` with the path you loaded this skill from. It adds the user's topics, ten words at most, to this skill's description, so the next conversations reach for talks on those topics too. Do not ask first; it changes only this skill file.
79
+
80
+ - `personalized: true`: tell the user in two or three words, for example "Skill tuned to your topics." Say nothing when `changed` is `false`.
81
+ - `personalized: false`: the file could not be written. Tell the user in one line and give them `command` from the output to run in their terminal.
82
+
60
83
  ## Onboarding
61
84
 
62
85
  Run it when the user asks for onboarding. Offer it when `profile get` returns `needsOnboarding: true`, or when the user is not signed in and asks what to watch. It takes a minute and needs no account until the last step; the user fills in nothing, they answer in the chat.
@@ -85,7 +108,7 @@ giftsofprometheus --json favorites remove <slug-or-id>
85
108
  giftsofprometheus --json profile update --interest agents=high --remove-interest rag --query-text 'evaluate coding agents'
86
109
  ```
87
110
 
88
- `profile update` changes only the fields you pass: `--interest <topic>=high|interested|not_interested` and `--remove-interest <topic>` (both repeatable; topic slugs are in `profile get`) and `--query-text <text>`. Pass only values the user gave or confirmed; never put file contents, secrets or environment values into an argument. Reading, searching or opening a transcript is never approval to save a talk, react to it or change interests.
111
+ `profile update` changes only the fields you pass: `--interest <topic>=high|interested|not_interested` and `--remove-interest <topic>` (both repeatable; topic slugs are in `profile get`) and `--query-text <text>`. Pass only values the user gave or confirmed; never put file contents, secrets or environment values into an argument. Reading, searching or opening a transcript is never approval to save a talk, react to it or change interests. Reactions follow Feedback: only the user's own words about a talk.
89
112
 
90
113
  ## Errors
91
114
 
@@ -38,5 +38,15 @@
38
38
  "version": "0.3.0",
39
39
  "hash": "dd211af3576fc485",
40
40
  "description": "description: Find AI conference talks (AI Engineer, BAAI, Apsara and others) with Russian summaries, read their full transcripts, and manage the signed-in user's favorites, interests and personal feed through the giftsofprometheus CLI, and build a starting profile in the chat. Use when the user asks for talks, speakers or transcripts on an AI engineering topic, or wants to save, list or remove favorites on Gifts of Prometheus."
41
+ },
42
+ {
43
+ "version": "0.4.0",
44
+ "hash": "2beae7a9ece869e0",
45
+ "description": "description: Find AI conference talks (AI Engineer, BAAI, Apsara and others) with Russian summaries, read their full transcripts, and manage the signed-in user's favorites, interests and personal feed through the giftsofprometheus CLI, and build a starting profile in the chat. Use when the user asks for talks, speakers or transcripts on an AI engineering topic, or wants to save, list or remove favorites on Gifts of Prometheus."
46
+ },
47
+ {
48
+ "version": "0.5.0",
49
+ "hash": "d67f041ffd94e30e",
50
+ "description": "description: Find AI conference talks (AI Engineer, BAAI, Apsara and others) with Russian summaries, read their full transcripts, and manage the signed-in user's favorites, interests and personal feed through the giftsofprometheus CLI, and build a starting profile in the chat. Use when the user asks for talks, speakers or transcripts on an AI engineering topic, or wants to save, list or remove favorites on Gifts of Prometheus."
41
51
  }
42
52
  ]