broader-vids 0.1.4 → 0.1.7
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/.claude-plugin/marketplace.json +19 -0
- package/.claude-plugin/plugin.json +9 -0
- package/README.md +40 -83
- package/bin/broader-vids.cjs +77 -8
- package/bin/plugin-install.cjs +163 -29
- package/docs/ARCHITECTURE.md +17 -6
- package/docs/REFERENCE.md +64 -3
- package/docs/SCORING.md +8 -4
- package/docs/WORKFLOW.md +5 -2
- package/package.json +7 -5
- package/plugin.json +1 -1
- package/python/{broader_vids-0.1.4-py3-none-any.whl → broader_vids-0.1.7-py3-none-any.whl} +0 -0
- package/skills/broader-vids/SKILL.md +2 -0
- package/skills/broader-vids-clean/SKILL.md +2 -0
- package/skills/broader-vids-dashboard/SKILL.md +2 -0
- package/skills/broader-vids-reset/SKILL.md +2 -0
- package/skills/broader-vids-setup/SKILL.md +2 -0
- package/skills/claude-host.md +46 -0
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "broader-vids",
|
|
3
|
+
"description": "Broader Vids plugin for Claude Code",
|
|
4
|
+
"owner": {
|
|
5
|
+
"name": "Broader Vids contributors"
|
|
6
|
+
},
|
|
7
|
+
"plugins": [
|
|
8
|
+
{
|
|
9
|
+
"name": "broader-vids",
|
|
10
|
+
"source": {
|
|
11
|
+
"source": "npm",
|
|
12
|
+
"package": "broader-vids",
|
|
13
|
+
"version": "latest",
|
|
14
|
+
"registry": "https://registry.npmjs.org"
|
|
15
|
+
},
|
|
16
|
+
"description": "Curated YouTube and Bilibili recommendations with local evidence and feedback."
|
|
17
|
+
}
|
|
18
|
+
]
|
|
19
|
+
}
|
package/README.md
CHANGED
|
@@ -1,33 +1,31 @@
|
|
|
1
1
|
# Broader Vids
|
|
2
2
|
|
|
3
|
-
Broader Vids provides an alternative recommendation algorithm for YouTube and Bilibili.
|
|
4
|
-
It combines your interests, exploration of unfamiliar topics, video quality, and feedback.
|
|
3
|
+
Broader Vids provides an alternative recommendation algorithm for YouTube and Bilibili. It combines your interests, exploration of unfamiliar topics, and video quality.
|
|
5
4
|
|
|
6
|
-
**
|
|
7
|
-
You can
|
|
8
|
-
Each complete round recommends ten videos per selected platform.
|
|
5
|
+
**Your dashboard ratings calibrate the plugin’s internal scoring models to your preferences.**
|
|
6
|
+
You can exclude creators and tags from future rounds. Each complete round recommends ten videos per selected platform.
|
|
9
7
|
|
|
10
|
-
The plugin runs locally through Codex CLI or Codex in the ChatGPT desktop app.
|
|
11
|
-
|
|
8
|
+
The plugin runs locally through Codex CLI or Codex in the ChatGPT desktop app. Recommendations appear in chat. A local dashboard manages ratings, exclusions, and preferences. Claude Code packaging is experimental. Static package checks and launcher fixtures cover it. No Claude host acceptance test has been performed.
|
|
9
|
+
|
|
10
|
+
## Requirements
|
|
11
|
+
|
|
12
|
+
Use Windows, PowerShell, Node.js 20 or later with npm, UV, and Codex CLI signed in with ChatGPT. Installation and recommendations require internet access.
|
|
12
13
|
|
|
13
14
|
## Install the plugin
|
|
14
15
|
|
|
15
|
-
|
|
16
|
-
Installation and recommendations require internet access.
|
|
17
|
-
Choose one installation method. Neither method requires a checkout, build, or local folder selection.
|
|
16
|
+
Choose one of these three remote installation routes. You do not need a repository checkout or a local build.
|
|
18
17
|
|
|
19
|
-
###
|
|
18
|
+
### ChatGPT desktop app
|
|
20
19
|
|
|
21
20
|
1. Open the plugin marketplace controls in Codex.
|
|
22
|
-
2. Select **Add marketplace** and its repository or Git URL option.
|
|
21
|
+
2. Select **Add marketplace** and choose its repository or Git URL option.
|
|
23
22
|
3. Enter `https://github.com/antidemosthenes/broader-vids`.
|
|
24
|
-
4. Add or sync the marketplace.
|
|
25
|
-
5.
|
|
26
|
-
6. Start a new conversation.
|
|
23
|
+
4. Add or sync the marketplace. Then install **Broader Vids**.
|
|
24
|
+
5. Start a new conversation.
|
|
27
25
|
|
|
28
|
-
The GitHub repository
|
|
26
|
+
The GitHub repository provides the catalog. The catalog downloads the plugin package from npm.
|
|
29
27
|
|
|
30
|
-
###
|
|
28
|
+
### Codex CLI from GitHub
|
|
31
29
|
|
|
32
30
|
Run these commands in PowerShell:
|
|
33
31
|
|
|
@@ -38,7 +36,7 @@ codex plugin add broader-vids@broader-vids
|
|
|
38
36
|
|
|
39
37
|
Start a new conversation after installation.
|
|
40
38
|
|
|
41
|
-
###
|
|
39
|
+
### npm
|
|
42
40
|
|
|
43
41
|
Run this command in PowerShell:
|
|
44
42
|
|
|
@@ -46,88 +44,47 @@ Run this command in PowerShell:
|
|
|
46
44
|
npx --yes broader-vids@latest plugin install
|
|
47
45
|
```
|
|
48
46
|
|
|
49
|
-
This command registers an npm
|
|
50
|
-
It installs the skills and dashboard, not only the terminal launcher.
|
|
51
|
-
It does not require the GitHub catalog.
|
|
52
|
-
Restart the desktop app or start a new Codex CLI conversation after installation.
|
|
47
|
+
This command registers an npm backed marketplace and installs the plugin skills and dashboard. Start a new conversation after installation.
|
|
53
48
|
|
|
54
|
-
The app
|
|
55
|
-
Use the npm command above for that installation route.
|
|
56
|
-
See the [official packaging guide](https://developers.openai.com/plugins/build/plugins) for supported plugin sources.
|
|
49
|
+
The desktop app accepts repository URLs in **Add marketplace**. Use the npm command for npm installation. See the [plugin packaging guide](https://developers.openai.com/plugins/build/plugins) for supported sources.
|
|
57
50
|
|
|
58
|
-
## Update the plugin
|
|
59
51
|
|
|
60
|
-
|
|
52
|
+
### Experimental Claude Code path
|
|
61
53
|
|
|
62
|
-
|
|
63
|
-
codex plugin marketplace upgrade broader-vids
|
|
64
|
-
codex plugin add broader-vids@broader-vids
|
|
65
|
-
```
|
|
66
|
-
|
|
67
|
-
For an npm installation, repeat the installation command:
|
|
54
|
+
Claude Code support is experimental. Static package checks and launcher fixtures cover it. No host acceptance test has been performed. These installation steps require a future npm release that contains the Claude files. See the [Claude Code installation notes](docs/REFERENCE.md#experimental-claude-code-installation).
|
|
68
55
|
|
|
69
|
-
|
|
70
|
-
npx --yes broader-vids@latest plugin install
|
|
71
|
-
```
|
|
72
|
-
|
|
73
|
-
In the desktop app, refresh the marketplace and select the current Broader Vids release.
|
|
74
|
-
If the app provides no update action, use the terminal commands for your installation method.
|
|
75
|
-
Start a new conversation and run setup after an update.
|
|
76
|
-
Setup installs the matching engine and preserves your saved profile.
|
|
77
|
-
Finish active recommendations and close the dashboard before updating.
|
|
78
|
-
|
|
79
|
-
## Set up and request recommendations
|
|
56
|
+
## Update the plugin
|
|
80
57
|
|
|
81
|
-
|
|
58
|
+
Follow [Update an installed plugin](docs/REFERENCE.md#update-an-installed-plugin) for update steps.
|
|
82
59
|
|
|
83
|
-
|
|
84
|
-
2. Choose YouTube, Bilibili, or both.
|
|
85
|
-
3. Choose calibrated starter preferences, enter your interests, or import a preference file.
|
|
86
|
-
4. Complete the dependency and access checks. Setup gives repair steps for required failures.
|
|
87
|
-
5. Invoke the recommendation skill. Review the links and summaries in chat.
|
|
88
|
-
6. Open the dashboard to mark watched videos and rate their topic, subject, depth, and quality.
|
|
89
|
-
7. Request another round when you want more recommendations.
|
|
60
|
+
## Set up and use Broader Vids
|
|
90
61
|
|
|
91
|
-
|
|
92
|
-
Saving ratings updates the local preference and quality models.
|
|
93
|
-
Their learned weights affect screening and final ranking in later rounds.
|
|
94
|
-
Creator and tag exclusions apply to the next new round.
|
|
95
|
-
The dashboard **Preferences** page lets you edit interests and import or export preferences and learned weights.
|
|
96
|
-
Before a new round, incomplete feedback prompts you to open the dashboard or continue.
|
|
62
|
+
Start a new conversation and invoke the setup skill. Choose YouTube, Bilibili, or both. Then choose starter preferences, enter interests, or import a preference file. Setup checks dependencies and access. It gives repair steps when a required check fails.
|
|
97
63
|
|
|
98
|
-
|
|
99
|
-
YouTube tag rules match available creator-supplied keyword tags, which differ from visible hashtags.
|
|
100
|
-
Bilibili rules match its video tags.
|
|
101
|
-
Search queries use English for YouTube and Simplified Chinese for Bilibili.
|
|
64
|
+
Invoke the recommendation skill to request a round. Review recommendations in chat. Open the dashboard to mark videos as watched and rate topic, subject, depth, and quality. Ratings update local preference and quality models. Their learned weights affect later rounds. Creator and tag exclusions apply to the next new round.
|
|
102
65
|
|
|
103
66
|
| Action | Skill command | Purpose |
|
|
104
67
|
| --- | --- | --- |
|
|
105
|
-
| Setup | `$broader-vids-setup` | Choose platforms and preferences
|
|
106
|
-
| Recommendations | `$broader-vids` | Request
|
|
107
|
-
| Dashboard | `$broader-vids-dashboard` | Rate videos
|
|
108
|
-
| Reset | `$broader-vids-reset` | Preview removal of preferences, weights, ratings, and histories
|
|
109
|
-
| Clean | `$broader-vids-clean` | Preview removal of all managed
|
|
110
|
-
|
|
111
|
-
Use the
|
|
112
|
-
|
|
113
|
-
You can also ask: “Use Broader Vids to recommend videos” or “Use Broader Vids to open my dashboard.”
|
|
68
|
+
| Setup | `$broader-vids-setup` | Choose platforms and preferences. Install tools and check access. |
|
|
69
|
+
| Recommendations | `$broader-vids` | Request videos for your saved platforms. |
|
|
70
|
+
| Dashboard | `$broader-vids-dashboard` | Rate videos. Manage exclusions and preferences. |
|
|
71
|
+
| Reset | `$broader-vids-reset` | Preview removal of preferences, weights, ratings, and histories. Keep tools and sign-in. |
|
|
72
|
+
| Clean | `$broader-vids-clean` | Preview removal of all managed data, including tools and sign-in. |
|
|
73
|
+
|
|
74
|
+
Use the skill commands shown in your host's skill menu. Some hosts add the plugin namespace, such as `$broader-vids:broader-vids-dashboard`. You can also ask Broader Vids to recommend videos or open the dashboard.
|
|
75
|
+
|
|
114
76
|
Reset and Clean require confirmation. Neither action uninstalls the plugin.
|
|
115
77
|
|
|
116
78
|
## Bilibili access and exclusions
|
|
117
79
|
|
|
118
|
-
Bilibili
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
80
|
+
Bilibili needs manual sign-in for full video evidence. Setup opens a separate browser. Keep it open after sign-in, then report completion in chat. Broader Vids checks the session and closes the browser. You can switch accounts from the dashboard.
|
|
81
|
+
|
|
82
|
+
Broader Vids imports your account blacklist after sign-in checks and before new rounds. Imported creator exclusions combine with your manual exclusions. A failed sync keeps the last complete copy. Use **Sync blacklist** in the dashboard to retry.
|
|
83
|
+
|
|
84
|
+
## Architecture and guides
|
|
123
85
|
|
|
124
|
-
|
|
125
|
-
Imported creator exclusions combine with your manual exclusions.
|
|
126
|
-
A failed sync preserves the last complete copy.
|
|
127
|
-
Use **Sync blacklist** in the dashboard to retry.
|
|
86
|
+
The Node launcher manages a versioned local Python engine, which stores profile data locally and serves the dashboard.
|
|
128
87
|
|
|
129
|
-
|
|
130
|
-
The [reference](docs/REFERENCE.md) covers terminal commands, troubleshooting, local builds, and maintenance.
|
|
131
|
-
The [architecture](docs/ARCHITECTURE.md) describes the launcher, engine, and local storage.
|
|
88
|
+
Read the [workflow](docs/WORKFLOW.md) for recommendation steps. Read the [scoring guide](docs/SCORING.md) for ranking and learning. The [reference](docs/REFERENCE.md) covers commands, troubleshooting, updates, and maintenance. The [architecture guide](docs/ARCHITECTURE.md) describes the launcher, engine, and local storage.
|
|
132
89
|
|
|
133
90
|
License: [MIT](LICENSE).
|
package/bin/broader-vids.cjs
CHANGED
|
@@ -91,16 +91,59 @@ function selectRoot(directory, env = process.env) {
|
|
|
91
91
|
}
|
|
92
92
|
}
|
|
93
93
|
|
|
94
|
+
function parseHost(args) {
|
|
95
|
+
let host = "codex";
|
|
96
|
+
let explicit = false;
|
|
97
|
+
const values = [];
|
|
98
|
+
for (let index = 0; index < args.length; index += 1) {
|
|
99
|
+
let selected;
|
|
100
|
+
if (args[index] === "--host") {
|
|
101
|
+
selected = args[++index];
|
|
102
|
+
if (!selected || selected.startsWith("--"))
|
|
103
|
+
throw new Error("--host requires codex or claude.");
|
|
104
|
+
} else if (args[index].startsWith("--host=")) {
|
|
105
|
+
selected = args[index].slice("--host=".length);
|
|
106
|
+
} else {
|
|
107
|
+
values.push(args[index]);
|
|
108
|
+
continue;
|
|
109
|
+
}
|
|
110
|
+
if (!["codex", "claude"].includes(selected))
|
|
111
|
+
throw new Error("--host must be codex or claude.");
|
|
112
|
+
if (explicit && host !== selected)
|
|
113
|
+
throw new Error("Use one host value per command.");
|
|
114
|
+
host = selected;
|
|
115
|
+
explicit = true;
|
|
116
|
+
}
|
|
117
|
+
return { args: values, host, explicit };
|
|
118
|
+
}
|
|
119
|
+
|
|
94
120
|
function commandIndex(args) {
|
|
95
121
|
let index = 0;
|
|
96
122
|
while (index < args.length) {
|
|
97
123
|
if (args[index] === "--data-dir") index += 2;
|
|
98
124
|
else if (args[index].startsWith("--data-dir=")) index += 1;
|
|
125
|
+
else if (args[index] === "--host") index += 2;
|
|
126
|
+
else if (args[index].startsWith("--host=")) index += 1;
|
|
99
127
|
else return index;
|
|
100
128
|
}
|
|
101
129
|
return -1;
|
|
102
130
|
}
|
|
103
131
|
|
|
132
|
+
function validateSetupArguments(args, index) {
|
|
133
|
+
for (let item = index + 1; item < args.length; item += 1) {
|
|
134
|
+
const value = args[item];
|
|
135
|
+
if (value === "--asr" || value === "--evidence") continue;
|
|
136
|
+
if (value === "--data-dir") {
|
|
137
|
+
item += 1;
|
|
138
|
+
continue;
|
|
139
|
+
}
|
|
140
|
+
if (value.startsWith("--data-dir=")) continue;
|
|
141
|
+
throw new Error(
|
|
142
|
+
"Use setup with optional --evidence, --asr, and --data-dir PATH.",
|
|
143
|
+
);
|
|
144
|
+
}
|
|
145
|
+
}
|
|
146
|
+
|
|
104
147
|
function invoke(command, args) {
|
|
105
148
|
const result = spawnSync(command, args, {
|
|
106
149
|
stdio: "inherit",
|
|
@@ -225,6 +268,9 @@ function recordRuntimeBuild(runtime, digest, packageRoot, groups) {
|
|
|
225
268
|
}
|
|
226
269
|
|
|
227
270
|
function main(args = process.argv.slice(2)) {
|
|
271
|
+
const selectedHost = parseHost(args);
|
|
272
|
+
args = selectedHost.args;
|
|
273
|
+
const host = selectedHost.host;
|
|
228
274
|
const packageRoot = path.resolve(__dirname, "..");
|
|
229
275
|
const manifest = JSON.parse(
|
|
230
276
|
fs.readFileSync(path.join(packageRoot, "package.json"), "utf8"),
|
|
@@ -236,21 +282,37 @@ function main(args = process.argv.slice(2)) {
|
|
|
236
282
|
args.length === 2 &&
|
|
237
283
|
["--help", "-h"].includes(args[1])
|
|
238
284
|
) {
|
|
239
|
-
console.log(
|
|
285
|
+
console.log(
|
|
286
|
+
"Usage: broader-vids plugin install [--host codex|claude] or broader-vids plugin update --host claude",
|
|
287
|
+
);
|
|
240
288
|
return;
|
|
241
289
|
}
|
|
242
|
-
if (
|
|
290
|
+
if (
|
|
291
|
+
index !== 0 ||
|
|
292
|
+
args.length !== 2 ||
|
|
293
|
+
!["install", "update"].includes(args[1])
|
|
294
|
+
)
|
|
243
295
|
throw new Error(
|
|
244
|
-
"Use broader-vids plugin install without profile arguments.",
|
|
296
|
+
"Use broader-vids plugin install, or plugin update --host claude, without profile arguments.",
|
|
245
297
|
);
|
|
246
298
|
const result = require("./plugin-install.cjs").installPlugin(
|
|
247
299
|
manifest.version,
|
|
248
300
|
invoke,
|
|
301
|
+
process.env,
|
|
302
|
+
host,
|
|
303
|
+
args[1],
|
|
249
304
|
);
|
|
250
305
|
console.log(JSON.stringify(result, null, 2));
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
306
|
+
if (args[1] === "update")
|
|
307
|
+
console.log(
|
|
308
|
+
"Start a new Claude Code session and run setup to refresh the matching runtime.",
|
|
309
|
+
);
|
|
310
|
+
else
|
|
311
|
+
console.log(
|
|
312
|
+
host === "claude"
|
|
313
|
+
? "Start a new Claude Code session and invoke the Broader Vids setup skill."
|
|
314
|
+
: "Start a new Codex conversation and invoke the Broader Vids setup skill.",
|
|
315
|
+
);
|
|
254
316
|
return;
|
|
255
317
|
}
|
|
256
318
|
if (args[index] === "data") {
|
|
@@ -306,7 +368,8 @@ function main(args = process.argv.slice(2)) {
|
|
|
306
368
|
if (result.status === "partial") process.exitCode = 2;
|
|
307
369
|
return;
|
|
308
370
|
}
|
|
309
|
-
if (args[
|
|
371
|
+
if (args[index] === "setup") {
|
|
372
|
+
validateSetupArguments(args, index);
|
|
310
373
|
const sourceWheel = bundledWheel(packageRoot, manifest.version);
|
|
311
374
|
const wheelRoot = path.dirname(sourceWheel);
|
|
312
375
|
return withSetup(root, () => {
|
|
@@ -424,12 +487,17 @@ function main(args = process.argv.slice(2)) {
|
|
|
424
487
|
error.data_directory = root;
|
|
425
488
|
throw error;
|
|
426
489
|
}
|
|
490
|
+
const engineArgs = [
|
|
491
|
+
...args.slice(0, index),
|
|
492
|
+
...(selectedHost.explicit ? ["--host", host] : []),
|
|
493
|
+
...args.slice(index),
|
|
494
|
+
];
|
|
427
495
|
return invoke(executable, [
|
|
428
496
|
"-m",
|
|
429
497
|
"broader_vids",
|
|
430
498
|
"--data-dir",
|
|
431
499
|
root,
|
|
432
|
-
...
|
|
500
|
+
...engineArgs,
|
|
433
501
|
]);
|
|
434
502
|
});
|
|
435
503
|
}
|
|
@@ -438,6 +506,7 @@ module.exports = {
|
|
|
438
506
|
defaultRoot,
|
|
439
507
|
dataRoot,
|
|
440
508
|
commandIndex,
|
|
509
|
+
parseHost,
|
|
441
510
|
cacheWheel,
|
|
442
511
|
selectedRoot,
|
|
443
512
|
selectRoot,
|
package/bin/plugin-install.cjs
CHANGED
|
@@ -28,20 +28,36 @@ function resolveCodex(env = process.env, platform = process.platform) {
|
|
|
28
28
|
);
|
|
29
29
|
}
|
|
30
30
|
|
|
31
|
-
function
|
|
32
|
-
|
|
33
|
-
const
|
|
34
|
-
|
|
31
|
+
function resolveClaude(env = process.env, platform = process.platform) {
|
|
32
|
+
if (platform !== "win32") return ["claude", []];
|
|
33
|
+
const directories = (env.PATH || env.Path || "").split(path.delimiter);
|
|
34
|
+
for (const directory of directories) {
|
|
35
|
+
const folder = directory.replace(/^"(.*)"$/, "$1");
|
|
36
|
+
if (!folder) continue;
|
|
37
|
+
const executable = path.join(folder, "claude.exe");
|
|
38
|
+
if (fs.existsSync(executable)) return [executable, []];
|
|
39
|
+
const script = path.join(
|
|
40
|
+
folder,
|
|
41
|
+
"node_modules",
|
|
42
|
+
"@anthropic-ai",
|
|
43
|
+
"claude-code",
|
|
44
|
+
"cli.js",
|
|
45
|
+
);
|
|
46
|
+
if (fs.existsSync(script)) return [process.execPath, [script]];
|
|
47
|
+
}
|
|
48
|
+
throw new Error(
|
|
49
|
+
"Install Claude Code CLI and add claude.exe to PATH before installing the plugin.",
|
|
35
50
|
);
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
function guardedDirectories(paths, message) {
|
|
54
|
+
for (const folder of paths) {
|
|
39
55
|
fs.mkdirSync(folder, { recursive: true });
|
|
40
|
-
if (fs.lstatSync(folder).isSymbolicLink())
|
|
41
|
-
throw new Error(
|
|
42
|
-
"The managed marketplace must not contain symbolic links.",
|
|
43
|
-
);
|
|
56
|
+
if (fs.lstatSync(folder).isSymbolicLink()) throw new Error(message);
|
|
44
57
|
}
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
function withMarketplaceLock(root, runInstall) {
|
|
45
61
|
const lock = path.join(root, "install.lock");
|
|
46
62
|
let handle;
|
|
47
63
|
try {
|
|
@@ -53,11 +69,30 @@ function installPlugin(version, run, env = process.env) {
|
|
|
53
69
|
);
|
|
54
70
|
throw error;
|
|
55
71
|
}
|
|
56
|
-
const catalog = path.join(directory, "marketplace.json");
|
|
57
|
-
const temporary = path.join(directory, `.${randomUUID()}.tmp`);
|
|
58
72
|
try {
|
|
73
|
+
return runInstall();
|
|
74
|
+
} finally {
|
|
75
|
+
fs.closeSync(handle);
|
|
76
|
+
fs.unlinkSync(lock);
|
|
77
|
+
}
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
function installCodexPlugin(version, run, env) {
|
|
81
|
+
const [command, prefix] = resolveCodex(env);
|
|
82
|
+
const home = path.resolve(
|
|
83
|
+
env.CODEX_HOME || path.join(os.homedir(), ".codex"),
|
|
84
|
+
);
|
|
85
|
+
const root = path.join(home, "broader-vids-npm");
|
|
86
|
+
const directory = path.join(root, ".agents", "plugins");
|
|
87
|
+
guardedDirectories(
|
|
88
|
+
[root, path.join(root, ".agents"), directory],
|
|
89
|
+
"The managed marketplace must not contain symbolic links.",
|
|
90
|
+
);
|
|
91
|
+
return withMarketplaceLock(root, () => {
|
|
92
|
+
const catalog = path.join(directory, "marketplace.json");
|
|
59
93
|
if (fs.existsSync(catalog) && fs.lstatSync(catalog).isSymbolicLink())
|
|
60
94
|
throw new Error("The managed catalog must not be a symbolic link.");
|
|
95
|
+
const temporary = path.join(directory, `.${randomUUID()}.tmp`);
|
|
61
96
|
const marketplace = {
|
|
62
97
|
name: "broader-vids-npm",
|
|
63
98
|
interface: { displayName: "Broader Vids (npm)" },
|
|
@@ -75,25 +110,124 @@ function installPlugin(version, run, env = process.env) {
|
|
|
75
110
|
},
|
|
76
111
|
],
|
|
77
112
|
};
|
|
78
|
-
fs.writeFileSync(temporary, JSON.stringify(marketplace, null, 2) + "\n", {
|
|
79
|
-
flag: "wx",
|
|
80
|
-
mode: 0o600,
|
|
81
|
-
});
|
|
82
|
-
fs.renameSync(temporary, catalog);
|
|
83
|
-
run(command, [...prefix, "plugin", "marketplace", "add", root]);
|
|
84
|
-
run(command, [...prefix, "plugin", "add", "broader-vids@broader-vids-npm"]);
|
|
85
|
-
return { status: "installed", marketplace: marketplace.name, version };
|
|
86
|
-
} finally {
|
|
87
113
|
try {
|
|
88
|
-
fs.
|
|
114
|
+
fs.writeFileSync(temporary, JSON.stringify(marketplace, null, 2) + "\n", {
|
|
115
|
+
flag: "wx",
|
|
116
|
+
mode: 0o600,
|
|
117
|
+
});
|
|
118
|
+
fs.renameSync(temporary, catalog);
|
|
119
|
+
run(command, [...prefix, "plugin", "marketplace", "add", root]);
|
|
120
|
+
run(command, [
|
|
121
|
+
...prefix,
|
|
122
|
+
"plugin",
|
|
123
|
+
"add",
|
|
124
|
+
"broader-vids@broader-vids-npm",
|
|
125
|
+
]);
|
|
126
|
+
return { status: "installed", marketplace: marketplace.name, version };
|
|
89
127
|
} finally {
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
128
|
+
fs.rmSync(temporary, { force: true });
|
|
129
|
+
}
|
|
130
|
+
});
|
|
131
|
+
}
|
|
132
|
+
|
|
133
|
+
function installClaudePlugin(version, run, env, operation = "install") {
|
|
134
|
+
const [command, prefix] = resolveClaude(env);
|
|
135
|
+
const home = path.resolve(
|
|
136
|
+
env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), ".claude"),
|
|
137
|
+
);
|
|
138
|
+
const root = path.join(home, "marketplaces", "broader-vids-npm");
|
|
139
|
+
const directory = path.join(root, ".claude-plugin");
|
|
140
|
+
const catalog = path.join(directory, "marketplace.json");
|
|
141
|
+
if (operation === "update" && !fs.existsSync(catalog))
|
|
142
|
+
throw new Error(
|
|
143
|
+
"The managed Claude marketplace is not installed. Run plugin install first.",
|
|
144
|
+
);
|
|
145
|
+
guardedDirectories(
|
|
146
|
+
[home, path.join(home, "marketplaces"), root, directory],
|
|
147
|
+
"The managed Claude marketplace must not contain symbolic links.",
|
|
148
|
+
);
|
|
149
|
+
return withMarketplaceLock(root, () => {
|
|
150
|
+
if (fs.existsSync(catalog) && fs.lstatSync(catalog).isSymbolicLink())
|
|
151
|
+
throw new Error(
|
|
152
|
+
"The managed Claude catalog must not be a symbolic link.",
|
|
153
|
+
);
|
|
154
|
+
const temporary = path.join(directory, `.${randomUUID()}.tmp`);
|
|
155
|
+
const marketplace = {
|
|
156
|
+
name: "broader-vids-npm",
|
|
157
|
+
description: "Broader Vids npm plugin catalog for Claude Code",
|
|
158
|
+
owner: { name: "Broader Vids contributors" },
|
|
159
|
+
plugins: [
|
|
160
|
+
{
|
|
161
|
+
name: "broader-vids",
|
|
162
|
+
source: {
|
|
163
|
+
source: "npm",
|
|
164
|
+
package: "broader-vids",
|
|
165
|
+
version,
|
|
166
|
+
registry: "https://registry.npmjs.org",
|
|
167
|
+
},
|
|
168
|
+
description:
|
|
169
|
+
"Curated YouTube and Bilibili recommendations with local evidence and feedback.",
|
|
170
|
+
},
|
|
171
|
+
],
|
|
172
|
+
};
|
|
173
|
+
try {
|
|
174
|
+
fs.writeFileSync(temporary, JSON.stringify(marketplace, null, 2) + "\n", {
|
|
175
|
+
flag: "wx",
|
|
176
|
+
mode: 0o600,
|
|
177
|
+
});
|
|
178
|
+
fs.renameSync(temporary, catalog);
|
|
179
|
+
if (operation === "install") {
|
|
180
|
+
run(command, [...prefix, "plugin", "marketplace", "add", root]);
|
|
181
|
+
run(command, [
|
|
182
|
+
...prefix,
|
|
183
|
+
"plugin",
|
|
184
|
+
"install",
|
|
185
|
+
"broader-vids@broader-vids-npm",
|
|
186
|
+
]);
|
|
94
187
|
}
|
|
188
|
+
run(command, [
|
|
189
|
+
...prefix,
|
|
190
|
+
"plugin",
|
|
191
|
+
"marketplace",
|
|
192
|
+
"update",
|
|
193
|
+
marketplace.name,
|
|
194
|
+
]);
|
|
195
|
+
run(command, [
|
|
196
|
+
...prefix,
|
|
197
|
+
"plugin",
|
|
198
|
+
"update",
|
|
199
|
+
"broader-vids@broader-vids-npm",
|
|
200
|
+
"--scope",
|
|
201
|
+
"user",
|
|
202
|
+
]);
|
|
203
|
+
return {
|
|
204
|
+
status: operation === "update" ? "updated" : "installed",
|
|
205
|
+
marketplace: marketplace.name,
|
|
206
|
+
version,
|
|
207
|
+
};
|
|
208
|
+
} finally {
|
|
209
|
+
fs.rmSync(temporary, { force: true });
|
|
95
210
|
}
|
|
96
|
-
}
|
|
211
|
+
});
|
|
212
|
+
}
|
|
213
|
+
|
|
214
|
+
function installPlugin(
|
|
215
|
+
version,
|
|
216
|
+
run,
|
|
217
|
+
env = process.env,
|
|
218
|
+
host = "codex",
|
|
219
|
+
operation = "install",
|
|
220
|
+
) {
|
|
221
|
+
if (!["install", "update"].includes(operation))
|
|
222
|
+
throw new Error("Operation must be install or update.");
|
|
223
|
+
if (operation === "update" && host !== "claude")
|
|
224
|
+
throw new Error(
|
|
225
|
+
"Plugin update is supported only for Claude; use the Codex marketplace upgrade workflow.",
|
|
226
|
+
);
|
|
227
|
+
if (host === "codex") return installCodexPlugin(version, run, env);
|
|
228
|
+
if (host === "claude")
|
|
229
|
+
return installClaudePlugin(version, run, env, operation);
|
|
230
|
+
throw new Error("Host must be codex or claude.");
|
|
97
231
|
}
|
|
98
232
|
|
|
99
|
-
module.exports = { installPlugin, resolveCodex };
|
|
233
|
+
module.exports = { installPlugin, resolveCodex, resolveClaude };
|
package/docs/ARCHITECTURE.md
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
# Architecture
|
|
2
2
|
|
|
3
3
|
Broader Vids has one Python engine.
|
|
4
|
-
The terminal, Codex skill, and local dashboard use that engine.
|
|
4
|
+
The terminal, Codex skill, Claude Code skills, and local dashboard use that engine.
|
|
5
5
|
The Node launcher installs and starts the engine.
|
|
6
6
|
Per-profile locks coordinate launcher commands and setup.
|
|
7
7
|
Ordinary commands can share the runtime. Setup requires exclusive access.
|
|
@@ -11,9 +11,15 @@ A stale or unreadable lock blocks later work until the operator checks for survi
|
|
|
11
11
|
The launcher has no stale-lock repair command and does not implement recommendation logic.
|
|
12
12
|
|
|
13
13
|
The GitHub marketplace and explicit npm installer both install the prepared npm plugin.
|
|
14
|
-
The npm
|
|
14
|
+
The npm installers register isolated host catalogs without GitHub access or profile access.
|
|
15
15
|
Setup installs the bundled engine into external profile storage after plugin installation.
|
|
16
16
|
|
|
17
|
+
Host selection changes the model provider and worker interface. It does not change the engine.
|
|
18
|
+
Claude commands pass `--host claude` and explicit model and effort values.
|
|
19
|
+
Codex remains the default host.
|
|
20
|
+
Claude score reuse requires the same saved model and effort.
|
|
21
|
+
Codex retains its existing score-cache policy.
|
|
22
|
+
Both hosts can use the same profile through the same explicit `--data-dir` path.
|
|
17
23
|
## Project files
|
|
18
24
|
|
|
19
25
|
```text
|
|
@@ -68,6 +74,7 @@ broader-vids/
|
|
|
68
74
|
asr-requirements.txt Locked transcription dependencies
|
|
69
75
|
*.whl Generated engine package, excluded from Git
|
|
70
76
|
scripts/
|
|
77
|
+
release.py Build, verify, and synchronize release artifacts
|
|
71
78
|
release_ci.py Patch planning, publication checks, and GitHub assets
|
|
72
79
|
versioning.py Validated release metadata synchronization
|
|
73
80
|
test.py Isolated parallel regression runner
|
|
@@ -111,7 +118,9 @@ flowchart LR
|
|
|
111
118
|
The web layer displays saved results and submits explicit user actions.
|
|
112
119
|
It does not contain a separate scoring algorithm.
|
|
113
120
|
The skill directs the host to call the engine.
|
|
114
|
-
`worker_context.py` resolves
|
|
121
|
+
`worker_context.py` resolves Codex model settings from local turn metadata.
|
|
122
|
+
Claude uses explicit model and effort settings. Its adapter lives in `claude_worker.py`.
|
|
123
|
+
Each round retains its saved host. Cancellation and deadlines stop owned worker processes.
|
|
115
124
|
New runs save that pair and pass it to planning and assessment CLI workers.
|
|
116
125
|
`recommendations/collection.py` continues candidate collection until 100 pass `screening.py` duration and raw engagement floors, or a saved limit stops collection.
|
|
117
126
|
Screening policy 5 combines metadata screening with learned interest and balances query coverage across thirty-five content-assessment slots.
|
|
@@ -174,6 +183,7 @@ Refresh requests carry a read version and a mutation generation.
|
|
|
174
183
|
Only one refresh group runs at a time.
|
|
175
184
|
A refresh requested during an active read waits until that read finishes.
|
|
176
185
|
Old video records stay in browser memory only while the server returns them, an earlier list uses them, or they have an unsaved rating draft.
|
|
186
|
+
The interface removes saved-status notes and inspector positions when their videos leave all retained lists and drafts.
|
|
177
187
|
The interface rejects responses from before a newer mutation.
|
|
178
188
|
It pauses background refresh while the tab is hidden or a write is active.
|
|
179
189
|
Refresh preserves active controls and pane positions.
|
|
@@ -261,7 +271,8 @@ Preference transfer accepts format 4 with learning model version 8 and feature v
|
|
|
261
271
|
Manual creator rules transfer separately from learning parameters and replace the manual lists transactionally on import.
|
|
262
272
|
The export omits account-specific blacklist copies and sign-in data.
|
|
263
273
|
It includes a bounded exploration summary with at most 1,024 nodes and aggregate counts and round ages.
|
|
264
|
-
It
|
|
274
|
+
It includes watched video IDs without titles, ratings, or recommendation records.
|
|
275
|
+
Import adds their watched state without clearing local video states.
|
|
265
276
|
It does not change SQLite schema 12.
|
|
266
277
|
A completed `preference_import` job stores the imported parameter baseline and local feedback cutoff.
|
|
267
278
|
Fitting combines that baseline with active ratings saved after the cutoff.
|
|
@@ -275,11 +286,11 @@ Input validation runs once per terminal or HTTP request.
|
|
|
275
286
|
Failed imports remove unused recovery files.
|
|
276
287
|
Import also removes obsolete model caches while preserving models referenced by recommendations or frozen evaluations.
|
|
277
288
|
An uncertain commit retains its recovery file.
|
|
278
|
-
|
|
289
|
+
Preference recovery files reside in `backups/` and include prior watched IDs and manual creator rules.
|
|
279
290
|
The dashboard uses authenticated local POST operations for export, preview, and import.
|
|
280
291
|
The transfer dialog preserves rating drafts and blocks stale polling responses during an operation.
|
|
281
292
|
|
|
282
|
-
Evidence corrections add derived records.
|
|
293
|
+
Evidence corrections add derived records, including the current missing-caption deduction.
|
|
283
294
|
They do not overwrite original scorecards or user ratings.
|
|
284
295
|
|
|
285
296
|
The Preferences page uses `preferences.js` to coordinate `/api/interests` and the preference-transfer endpoints.
|
package/docs/REFERENCE.md
CHANGED
|
@@ -807,6 +807,10 @@ Dashboard browser tests require Playwright and a supported local browser.
|
|
|
807
807
|
Local Windows browser tests use installed Edge by default.
|
|
808
808
|
CI installs the Playwright Chromium headless shell on both operating systems.
|
|
809
809
|
Set `BROADER_VIDS_TEST_BROWSER=chromium` to use that browser locally.
|
|
810
|
+
Windows CI first installs the headless browser without changing system components.
|
|
811
|
+
If installation fails, it retries with the required system dependencies.
|
|
812
|
+
Linux CI installs those dependencies before tests.
|
|
813
|
+
Both paths retain browser validation and the full test suite.
|
|
810
814
|
Linux tests use Playwright Chromium. Install its browser and system dependencies before running tests:
|
|
811
815
|
|
|
812
816
|
```bash
|
|
@@ -822,6 +826,27 @@ Dashboard tests check rating saves, drafts, duplicate feedback, dialogs, and pla
|
|
|
822
826
|
Keep screenshots and other visual checks under the ignored `.cache/` directory.
|
|
823
827
|
Browser tests reuse a browser process within each worker and create a fresh context for each test.
|
|
824
828
|
|
|
829
|
+
## Experimental Claude Code installation
|
|
830
|
+
|
|
831
|
+
Claude Code support is experimental. Static package checks and launcher fixtures cover this path. No Claude CLI installation, skill loading, recommendation, or host acceptance test has been performed. This change does not publish an npm release. Use these commands after an npm release includes the Claude files.
|
|
832
|
+
|
|
833
|
+
Install from npm with the launcher:
|
|
834
|
+
|
|
835
|
+
```powershell
|
|
836
|
+
npx --yes broader-vids@latest plugin install --host claude
|
|
837
|
+
```
|
|
838
|
+
|
|
839
|
+
The launcher creates an isolated marketplace under `~/.claude/marketplaces/broader-vids-npm`, then calls Claude's native marketplace commands. It records the running npm package version in its catalog.
|
|
840
|
+
|
|
841
|
+
You can also install from the repository marketplace:
|
|
842
|
+
|
|
843
|
+
```powershell
|
|
844
|
+
claude plugin marketplace add antidemosthenes/broader-vids
|
|
845
|
+
claude plugin install broader-vids@broader-vids
|
|
846
|
+
```
|
|
847
|
+
|
|
848
|
+
The root Claude catalog tracks the npm `latest` release. See the [Claude Code plugin guide](https://code.claude.com/docs/en/plugins/create) for the host format. The installed skills route Claude to the host-specific instructions in [Claude host guide](../skills/claude-host.md).
|
|
849
|
+
|
|
825
850
|
## Remote plugin installation
|
|
826
851
|
|
|
827
852
|
The [README](../README.md#install-the-plugin) gives GitHub and npm installation procedures.
|
|
@@ -956,6 +981,8 @@ An existing Git tag reserves its version, even when npm publication did not fini
|
|
|
956
981
|
A different source receives a later version. A retry of the same source can reuse its tag.
|
|
957
982
|
A higher version declared in the source acts as a minimum for the release version.
|
|
958
983
|
The workflow synchronizes Node, Python, plugin, lock-file, and wheel-whitelist versions in a temporary release checkout.
|
|
984
|
+
Staging uses the version synchronizer's file list, including both host manifests.
|
|
985
|
+
Unstaged tracked changes stop the release before tag creation.
|
|
959
986
|
It records the tested source commit in `package.json` under `broaderVidsRelease.sourceCommit`.
|
|
960
987
|
It writes the version commit to main and creates its `vX.Y.Z` tag in one atomic push.
|
|
961
988
|
The commit contains the tested functional source with synchronized release metadata.
|
|
@@ -980,6 +1007,8 @@ It retains workflow artifacts for seven days.
|
|
|
980
1007
|
Retries resolve a tagged version commit back to its tested merge source.
|
|
981
1008
|
They reuse a release when its recorded source commit matches that source.
|
|
982
1009
|
An existing tag must have the expected parent and exact release tree.
|
|
1010
|
+
Rerunning publication cannot repair a tag with mismatched manifest versions.
|
|
1011
|
+
Keep that tag and merge a corrected main update to release a later version.
|
|
983
1012
|
The bot version commit does not allocate a second version.
|
|
984
1013
|
GitHub does not start another push workflow for a commit pushed with the workflow's `GITHUB_TOKEN`.
|
|
985
1014
|
See [GitHub's trigger rules](https://docs.github.com/en/actions/how-tos/write-workflows/choose-when-workflows-run/trigger-a-workflow).
|
|
@@ -1026,14 +1055,14 @@ The account settings and the first live OIDC publication require separate accept
|
|
|
1026
1055
|
### Update an installed plugin
|
|
1027
1056
|
|
|
1028
1057
|
Finish active recommendations and stop the dashboard before updating.
|
|
1029
|
-
For a GitHub installation:
|
|
1058
|
+
For a Codex GitHub installation:
|
|
1030
1059
|
|
|
1031
1060
|
```powershell
|
|
1032
1061
|
codex plugin marketplace upgrade broader-vids
|
|
1033
1062
|
codex plugin add broader-vids@broader-vids
|
|
1034
1063
|
```
|
|
1035
1064
|
|
|
1036
|
-
For
|
|
1065
|
+
For a Codex npm installation:
|
|
1037
1066
|
|
|
1038
1067
|
```powershell
|
|
1039
1068
|
npx --yes broader-vids@latest plugin install
|
|
@@ -1053,6 +1082,30 @@ Start a new conversation and run the setup skill after updating.
|
|
|
1053
1082
|
Setup refreshes the matching runtime and preserves preferences, ratings, history, exclusions, and sign-in.
|
|
1054
1083
|
An update does not run Reset or Clean.
|
|
1055
1084
|
|
|
1085
|
+
#### Update experimental Claude Code support
|
|
1086
|
+
|
|
1087
|
+
For the repository marketplace:
|
|
1088
|
+
|
|
1089
|
+
```powershell
|
|
1090
|
+
claude plugin marketplace update broader-vids
|
|
1091
|
+
claude plugin update broader-vids@broader-vids --scope user
|
|
1092
|
+
```
|
|
1093
|
+
|
|
1094
|
+
For the managed npm marketplace:
|
|
1095
|
+
|
|
1096
|
+
```powershell
|
|
1097
|
+
npx --yes broader-vids@latest plugin update --host claude
|
|
1098
|
+
```
|
|
1099
|
+
|
|
1100
|
+
The npm command updates the managed catalog's pinned version, refreshes the listing, and updates the installed user-scope plugin.
|
|
1101
|
+
Use `plugin install --host claude` for the first installation.
|
|
1102
|
+
Installation also synchronizes the plugin version after registration.
|
|
1103
|
+
A marketplace refresh alone does not update installed Claude plugins.
|
|
1104
|
+
Start a new Claude session and run `/broader-vids:broader-vids-setup` after an update.
|
|
1105
|
+
The new engine preserves the selected profile.
|
|
1106
|
+
These commands follow the [Claude plugin command reference](https://code.claude.com/docs/en/plugins/cli-reference).
|
|
1107
|
+
Actual Claude-host update behavior remains unverified in this project.
|
|
1108
|
+
|
|
1056
1109
|
### Repair the installed runtime
|
|
1057
1110
|
|
|
1058
1111
|
From an unpacked package, install its external engine:
|
|
@@ -1080,6 +1133,7 @@ Its `installed` status does not mean onboarding is complete.
|
|
|
1080
1133
|
Use the guided setup skill to configure interests, choose platforms, and check access.
|
|
1081
1134
|
`setup --evidence` also installs browser and media tools.
|
|
1082
1135
|
`setup --asr` includes those tools and transcription dependencies.
|
|
1136
|
+
Setup rejects unsupported options before it changes the profile or runtime.
|
|
1083
1137
|
The receipt records `core`, `evidence`, and `asr` only when setup installed those groups, with each group's requirements-file digest.
|
|
1084
1138
|
Setup requires Node.js 20 or later and UV.
|
|
1085
1139
|
It does not use an npm postinstall script.
|
|
@@ -1218,7 +1272,14 @@ Continue only after you restore access.
|
|
|
1218
1272
|
Browser sign-in is not imported automatically. Increasing the request cap does not repair an access challenge.
|
|
1219
1273
|
They share one request counter and retain the existing access checks.
|
|
1220
1274
|
Video downloads omit audio unless transcription requires it.
|
|
1221
|
-
|
|
1275
|
+
The engine checks selected-stream sizes before transfer.
|
|
1276
|
+
It uses reported exact sizes, reported estimates, or duration multiplied by bitrate, in that order.
|
|
1277
|
+
Transcription downloads include both video and audio in this check.
|
|
1278
|
+
If the estimate exceeds the remaining allowance, the engine tries a smaller offered format within the existing resolution and audio rules.
|
|
1279
|
+
When partial media exists, continuation resolves saved format IDs against fresh metadata and checks their codecs and resolution.
|
|
1280
|
+
If the original selection is unavailable, the engine skips the candidate and removes its owned partial files.
|
|
1281
|
+
Cumulative download charges remain unchanged.
|
|
1282
|
+
Unknown sizes still use the transfer byte limit.
|
|
1222
1283
|
Transfer checkpoints record observed bytes and bound unreported bytes after interruption.
|
|
1223
1284
|
Reports identify conservative byte charges as upper bounds.
|
|
1224
1285
|
|
package/docs/SCORING.md
CHANGED
|
@@ -4,6 +4,9 @@ Broader Vids learns conditional preferences from explicit feedback.
|
|
|
4
4
|
It does not estimate an objective quality score for every video.
|
|
5
5
|
Its conclusions apply to the retrieved videos and feature contexts that receive feedback.
|
|
6
6
|
|
|
7
|
+
Claude Code uses the same scoring formulas and thresholds as Codex.
|
|
8
|
+
The selected provider and model can change generated assessments.
|
|
9
|
+
No host selection changes the saved scoring formulas.
|
|
7
10
|
## Terms
|
|
8
11
|
|
|
9
12
|
| Term | Meaning |
|
|
@@ -162,10 +165,10 @@ Search-domain labels describe retrieval context.
|
|
|
162
165
|
They do not prove the video's semantic topic.
|
|
163
166
|
|
|
164
167
|
New AI topic labels must be short subject names, with at most 120 characters and 12 words.
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
168
|
+
Fresh assessments and reads of saved scorecards omit unusable topic labels before validation.
|
|
169
|
+
The filter removes obvious citations, instructions, control characters, and editing notes from the label lists.
|
|
170
|
+
The engine retains the raw model response and preserves numeric quality scores, saved ratings, and explicit user targets.
|
|
171
|
+
Remaining schema or evidence errors use the existing bounded assessment fix workflow.
|
|
169
172
|
This check detects common formatting errors. It does not prove that a topic correctly describes the video.
|
|
170
173
|
|
|
171
174
|
Source links, repost declarations, `中配`, and YouDub disclosures inform originality assessment.
|
|
@@ -388,6 +391,7 @@ A new response type requires new holdout coverage.
|
|
|
388
391
|
Training on released labels does not replace the earlier test result.
|
|
389
392
|
|
|
390
393
|
Evidence maintenance adds derived feature records after source checks.
|
|
394
|
+
Corrections include the current missing-caption deduction, which replaces any earlier deduction.
|
|
391
395
|
They preserve original ratings, scorecards, and captured features.
|
|
392
396
|
Incomplete source metadata can pause quality fitting.
|
|
393
397
|
Maintenance uses retained frames and captions without downloading replacement media.
|
package/docs/WORKFLOW.md
CHANGED
|
@@ -4,9 +4,12 @@ Broader Vids finds videos, checks their content, and learns from explicit feedba
|
|
|
4
4
|
This document explains the user workflow.
|
|
5
5
|
See the [terminal reference](REFERENCE.md) for commands.
|
|
6
6
|
|
|
7
|
+
Codex remains the default host. Claude Code uses the same workflow and evidence rules.
|
|
8
|
+
Pass `--host claude` before an engine command and supply Claude's active model and effort explicitly.
|
|
9
|
+
Provider and model changes can change generated plans and assessments. They do not change collection or feedback gates.
|
|
7
10
|
## 1. Complete setup and check readiness
|
|
8
11
|
|
|
9
|
-
Use the [
|
|
12
|
+
Use the [update procedure](REFERENCE.md#update-an-installed-plugin) to update an installed plugin.
|
|
10
13
|
Finish active work before updating. Start a new conversation and run setup to prepare the matching engine.
|
|
11
14
|
Setup preserves the existing profile unless you explicitly request Reset or Clean.
|
|
12
15
|
|
|
@@ -131,7 +134,7 @@ The two-platform command runs these paths with shared workers and an optional to
|
|
|
131
134
|
```mermaid
|
|
132
135
|
flowchart TD
|
|
133
136
|
S["Recommendation request"] --> T{"Onboarding complete?"}
|
|
134
|
-
T -- No --> U["Introduce features; choose platforms; import preferences or enter interests"]
|
|
137
|
+
T -- No --> U["Introduce features; choose platforms; choose a starter, import preferences, or enter interests"]
|
|
135
138
|
U --> V["Install required tools and check selected platform access"]
|
|
136
139
|
V -- "Failure: repair and retry" --> V
|
|
137
140
|
V --> W["Record setup completion"]
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "broader-vids",
|
|
3
|
-
"version": "0.1.
|
|
4
|
-
"description": "Codex
|
|
3
|
+
"version": "0.1.7",
|
|
4
|
+
"description": "Codex and experimental Claude Code skills for local YouTube/Bilibili recommendations",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"engines": {
|
|
7
7
|
"node": ">=20"
|
|
@@ -11,7 +11,7 @@
|
|
|
11
11
|
},
|
|
12
12
|
"files": [
|
|
13
13
|
"bin/",
|
|
14
|
-
"python/broader_vids-0.1.
|
|
14
|
+
"python/broader_vids-0.1.7-*.whl",
|
|
15
15
|
"python/core-requirements.txt",
|
|
16
16
|
"python/evidence-requirements.txt",
|
|
17
17
|
"python/asr-requirements.txt",
|
|
@@ -22,7 +22,9 @@
|
|
|
22
22
|
"docs/WORKFLOW.md",
|
|
23
23
|
"docs/ARCHITECTURE.md",
|
|
24
24
|
"docs/SCORING.md",
|
|
25
|
-
"docs/REFERENCE.md"
|
|
25
|
+
"docs/REFERENCE.md",
|
|
26
|
+
".claude-plugin/plugin.json",
|
|
27
|
+
".claude-plugin/marketplace.json"
|
|
26
28
|
],
|
|
27
29
|
"scripts": {
|
|
28
30
|
"test": "node --test tests/launcher.test.cjs tests/profile-data.test.cjs",
|
|
@@ -46,6 +48,6 @@
|
|
|
46
48
|
"tag": "latest"
|
|
47
49
|
},
|
|
48
50
|
"broaderVidsRelease": {
|
|
49
|
-
"sourceCommit": "
|
|
51
|
+
"sourceCommit": "61855b21530fa3ce0c35a7cd0afda7468e234f8a"
|
|
50
52
|
}
|
|
51
53
|
}
|
package/plugin.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
|
|
3
3
|
"name": "broader-vids",
|
|
4
|
-
"version": "0.1.
|
|
4
|
+
"version": "0.1.7",
|
|
5
5
|
"description": "Curated YouTube and Bilibili recommendations with bounded quality evidence and local watched/feedback state.",
|
|
6
6
|
"license": "MIT",
|
|
7
7
|
"extensions": {
|
|
Binary file
|
|
@@ -3,6 +3,8 @@ name: broader-vids
|
|
|
3
3
|
description: Recommend YouTube and Bilibili videos with local evidence and feedback. Use for video discovery, recommendation rounds, video ratings, run recovery, and recommendation token reports.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
+
> **Claude Code:** Read [the Claude host guide](../claude-host.md) and follow it instead of the Codex-specific instructions below.
|
|
7
|
+
|
|
6
8
|
# Broader Vids
|
|
7
9
|
|
|
8
10
|
Keep launcher commands internal.
|
|
@@ -3,6 +3,8 @@ name: broader-vids-clean
|
|
|
3
3
|
description: Remove the complete Broader Vids data directory while retaining the installed plugin. Use only for full local-data removal, not routine media cleanup.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
+
> **Claude Code:** Read [the Claude host guide](../claude-host.md) and follow it instead of the Codex-specific instructions below.
|
|
7
|
+
|
|
6
8
|
# Clean Broader Vids data
|
|
7
9
|
|
|
8
10
|
Keep launcher commands internal.
|
|
@@ -3,6 +3,8 @@ name: broader-vids-dashboard
|
|
|
3
3
|
description: Open, inspect, or stop the Broader Vids local dashboard for recommendation feedback, optional calibration, token usage reports, and creator or tag exclusions. Use only for Broader Vids dashboard requests.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
+
> **Claude Code:** Read [the Claude host guide](../claude-host.md) and follow it instead of the Codex-specific instructions below.
|
|
7
|
+
|
|
6
8
|
# Broader Vids dashboard
|
|
7
9
|
|
|
8
10
|
Keep launcher commands internal.
|
|
@@ -3,6 +3,8 @@ name: broader-vids-reset
|
|
|
3
3
|
description: Reset Broader Vids preferences, learned weights, ratings, exclusions, and histories for a fresh start while retaining tools and Bilibili sign-in.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
+
> **Claude Code:** Read [the Claude host guide](../claude-host.md) and follow it instead of the Codex-specific instructions below.
|
|
7
|
+
|
|
6
8
|
# Reset Broader Vids
|
|
7
9
|
|
|
8
10
|
Keep launcher commands internal.
|
|
@@ -3,6 +3,8 @@ name: broader-vids-setup
|
|
|
3
3
|
description: Set up an installed Broader Vids plugin, its external Python runtime, local video interests, and platform access. Use for Broader Vids onboarding or installation repair, not general environment setup.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
+
> **Claude Code:** Read [the Claude host guide](../claude-host.md) and follow it instead of the Codex-specific instructions below.
|
|
7
|
+
|
|
6
8
|
# Set up Broader Vids
|
|
7
9
|
|
|
8
10
|
## Completion output
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
# Claude Code host guide
|
|
2
|
+
|
|
3
|
+
This guide is for Claude Code. Use it instead of the Codex-specific instructions in the five Broader Vids skill files.
|
|
4
|
+
|
|
5
|
+
## Host and engine rules
|
|
6
|
+
|
|
7
|
+
- Keep the user's selected profile stable. Run `data show` and pass its absolute path with `--data-dir` on every engine command.
|
|
8
|
+
- Resolve the plugin root from the installed skill path. Run the Node launcher from that root.
|
|
9
|
+
- Put `--host claude` before each engine subcommand. For example, run `node <plugin-root>/bin/broader-vids.cjs --host claude recommend`.
|
|
10
|
+
- The Node launcher handles `data show`, `data use`, `data reset`, `reset`, and `clean`. It consumes `--host` for these commands.
|
|
11
|
+
- Run `setup --host claude --evidence` only to install or repair the runtime. The Node setup command does not complete onboarding.
|
|
12
|
+
- Use Claude's active model and effort only when Claude exposes both values in the current session. Otherwise ask the user once for both values and wait. Never infer either value from Codex, an old setting, or a default.
|
|
13
|
+
- Pass the verified values with `--model MODEL --effort EFFORT` for setup completion and recommendation commands. The engine can also read `BROADER_VIDS_CLAUDE_MODEL` and `BROADER_VIDS_CLAUDE_EFFORT` when the user explicitly sets both values.
|
|
14
|
+
- Keep launcher commands internal. Report results and repair steps in ordinary chat.
|
|
15
|
+
|
|
16
|
+
## Setup
|
|
17
|
+
|
|
18
|
+
Use the setup skill's workflow as described here, with the engine's returned questions. Do not apply its Codex-specific host checks. Ask one question at a time. Do not invent interests, select a platform, or import a file without the user's answer.
|
|
19
|
+
|
|
20
|
+
Check Node.js, UV, Claude CLI, FFmpeg, yt-dlp, Pillow, and the selected platform access. Use the Node launcher setup command to install the runtime. Use `doctor` for diagnostics. Preserve a working profile during repair.
|
|
21
|
+
|
|
22
|
+
Use `onboarding questions`, `onboarding status`, `profile show`, and `onboarding configure` as required by the engine. Preview starter preferences or imports before applying them. Open Bilibili sign-in only when needed. Wait for the user to report sign-in completion, then check access.
|
|
23
|
+
|
|
24
|
+
Complete onboarding with `onboarding complete --format chat --model MODEL --effort EFFORT`. Include the exact active Claude model and effort. If the engine reports a required failure, repair it and repeat completion. Do not report success while an answer or required check is pending.
|
|
25
|
+
|
|
26
|
+
For a successful explicit setup request, return the full guide produced by `onboarding complete --format chat`. When setup interrupts a recommendation request, continue that request after setup succeeds.
|
|
27
|
+
|
|
28
|
+
## Recommendations
|
|
29
|
+
|
|
30
|
+
Use the recommendation skill's engine workflow, evidence rules, saved profile, and feedback gate. Run one recommendation command with `--host claude`, the verified `--model` and `--effort`, and the requested platform options.
|
|
31
|
+
|
|
32
|
+
Do not bypass incomplete feedback without the user's explicit choice. Do not reduce requested platform coverage. Report incomplete results as partial and keep candidate failure details accurate. Continue a paused run only when the user asks.
|
|
33
|
+
|
|
34
|
+
## Dashboard
|
|
35
|
+
|
|
36
|
+
Open the dashboard by running the engine's `dashboard` command with `--host claude`. Use the returned local URL. Do not start another server when one is already active. Stop only the verified Broader Vids dashboard for the selected profile.
|
|
37
|
+
|
|
38
|
+
The dashboard manages ratings, exclusions, interests, imports, and token reports. Do not create ratings or change preferences without the user's instruction. Dashboard access does not require a recommendation round.
|
|
39
|
+
|
|
40
|
+
## Reset
|
|
41
|
+
|
|
42
|
+
Run `reset` without apply flags first. Show the exact profile path, removal summary, retained items, unknown files, and blockers. Apply Reset only when the user explicitly requests it for that previewed path. Stop the verified dashboard first. Pass the same `--data-dir` and exact confirmation path. Preserve unknown files and report partial failures.
|
|
43
|
+
|
|
44
|
+
## Clean
|
|
45
|
+
|
|
46
|
+
Run `clean` without apply flags first. Show the exact profile path, removal summary, unknown files, and blockers. Apply Clean only when the user explicitly requests it for that previewed path. Stop the verified dashboard first. Pass the same `--data-dir` and exact confirmation path. Do not remove unknown files as a workaround. Report partial failures and offer setup if the user wants to use Broader Vids again.
|