Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 10 additions & 1 deletion .agents/skills/verify-deepseekbot/features/skill-invocation.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ A Human types `/` in a PersonaBot DM or Group Channel, picks a Skill, and sends
## Sub-features

- `menu` lists composer commands first, then Skills: Host Skills and the Project Skills under each conversation member Bot's Memory Repository `.agents/skills` or `.dsh/skills`. Each row shows its owner (Bot avatar or Skill icon), `/name` and a one-line description.
- `live-refresh` invalidates only the changed Bot's Project Skill catalog, or every Bot's Host portion when an unfiltered DSH `skills/change` reveals a changed Host catalog, and pushes `skills/catalog-changed` through the existing roster stream. `skills-list` reads the same fresh catalog as the menu.
- `rank` orders Skills by name prefix, then name subsequence, then owning Bot display name or slug substring, then description substring; order within each tier stays stable. Typing `alice` lists all of Alice's Skills.
- `chip` inserts the picked Skill as one token; Backspace removes it whole; the draft keeps it across reloads.
- `snapshot` stores `{name, owner, path, content}` with the message; editing or deleting the `SKILL.md` later does not change the sent message.
Expand Down Expand Up @@ -40,9 +41,17 @@ Preconditions: `launch` reported a model credential and `doctor` passes.
6. For a same-named command/Skill, inspect commands-first ordering, exercise the bare command, then explicitly select the Skill row and inspect the snapshot.
7. Through the designated Discord/Lark test destination and the IM browser QA procedure, inspect a mirrored Human message: it shows plain `/qa-echo`, with no brackets, XML or snapshot content. Correlate it with Source Event/Outbox facts. The automated provider-carrier tests alone do not verify browser rendering; do not infer that a Group bridge automatically forwards Human messages.

### Live refresh path

1. Keep Alice's DM composer and `/` menu open. Add, edit the description of, and delete `<memory>/.agents/skills/qa-live/SKILL.md`; repeat under `.dsh/skills`. Each change updates the menu without navigation or a page reload. Bob's unrelated DM does not refetch its Project Skill catalog.
2. Inspect the existing roster stream: `skills/catalog-changed` has `{botSlugs: ["alice"], channelIds: [<Alice DM>, <Groups containing Alice>]}`. Read `channelSkillCatalog` and run `deepseekbot skills-list --bot alice` after each event: both show the new description or absence. A Group containing Alice updates too. A subsequent unfiltered DSH Project notification must not broadcast to unrelated Channels when the Host catalog is unchanged.
3. Add/remove or edit a Host Skill: `skills/change` invalidates every Bot's Host catalog portion; Project Skill reads remain cached. An interrupted/reconnected Client roster stream refetches the selected channel on its replacement baseline.
4. Run `deepseekbot memory-move` for Alice, then edit her Skill at the new path. The event and menu still update. Remove Alice through the confirmed Bot deletion flow: her watchers stop. Disposing the isolated Host releases all Skill watchers and pending notifications.
5. Automated coverage: `packages/core/test/skill-catalog-refresh.test.ts` observes per-cwd registry calls, real filesystem add/modify/delete, Memory moves/removal/disposal, CLI/RPC equality, access-filtered SSE/typed push, and real DSH Registry invalidation through its registration control while preserving Agent Scope visibility. `packages/client/test/skill-catalog-live.test.ts` checks event parsing, subscription scope, reconnect baselines and shared-carrier cleanup.

## Gotchas

- The `/` menu reads the catalog when the conversation opens. A Skill written while the conversation is open appears after reopening it until S3 (live refresh) lands.
- The non-UI S3 slice exposes `actions.subscribeSkillCatalog(channelId, invalidate)` alongside `actions.skillCatalog(channelId)`. The UI owner must wire the mounted composer to refetch on invalidation, prefetch on open, ignore stale async completions, and unsubscribe on channel change/unmount. Until that wiring lands, live menu behavior in steps 1–4 remains unverified.
- DSH discovers `<memory>/.agents/skills` because the Orchestrator's cwd is the Memory Repository; a Skill placed in `.botharness/` is not found.
- Recalling an older message with ArrowUp, or restoring a failed send, keeps `/name` as plain text without the chip.

Expand Down
1 change: 1 addition & 0 deletions apps/docs/test/docs-reference.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -110,6 +110,7 @@ describe("generated developer reference", () => {
{ name: "approval/request", direction: "consumes", operation: "on" },
{ name: "botharness/personabot/activity", direction: "emits", operation: "emit" },
{ name: "session/event", direction: "consumes", operation: "on" },
{ name: "skills/change", direction: "consumes", operation: "on" },
{ name: "subagent/start", direction: "consumes", operation: "on" },
{ name: "system-prompt/assemble", direction: "consumes", operation: "on" },
{ name: "system-prompt/assemble", direction: "consumes", operation: "on" },
Expand Down
1 change: 1 addition & 0 deletions apps/mobile/src/host/wire.ts
Original file line number Diff line number Diff line change
Expand Up @@ -402,6 +402,7 @@ export interface WireGroupJoinRequest {
}

export type RosterLiveFrame =
| { type: 'skills'; change: { botSlugs: string[]; channelIds: string[] } }
| { type: 'attention' }
| { type: 'baseline'; placements: unknown[] }
| { type: 'changed' }
Expand Down
11 changes: 11 additions & 0 deletions changes/4234-live-skill-catalog.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
---
section: Fixed
---

## en

- Skill catalogs now invalidate on Host Skill changes and changes to `SKILL.md` in a Bot's Memory Repository, with scoped live notifications and fresh `skills-list` results; Client subscriptions can refresh the open conversation without polling ([#4234](https://github.com/BotHarness/BotHarness/issues/4234)).

## zh

- Host Skill 或 Bot Memory Repository 中的 `SKILL.md` 变化后,Skill 目录会按范围失效并推送通知,`skills-list` 也会读取最新结果;Client 可通过订阅刷新当前会话,无需轮询([#4234](https://github.com/BotHarness/BotHarness/issues/4234))。
8 changes: 8 additions & 0 deletions docs/architecture/botharness-architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -981,6 +981,14 @@ Registry 在 Generation 66 持久化不可恢复的身份关闭状态和确认

Zip 使用既有已认证 RPC 上传 256 KiB 原始数据块,避免整包超过加密网关的单请求边界。手机保留应用内文件、SHA-256 与大小;Host 暂存清单和不可变分块支持重启后核对,完整校验后才通过既有导入 owner 发布。暂存最多八个未过期会话、合计 400 MiB 预留,每个会话自首次接收起 24 小时到期;新上传接收时回收过期内容。规范导入回执独立于暂存期限,已完成操作无需原文件即可查回;未完成操作若需重选文件,必须匹配原哈希和大小。该暂存仅负责传输,不成为 Memory 或 Bot 的第二份权威。

### Skill catalog live refresh(#4234)

Skill 文件仍由 [ADR-0345](../adr/0345-project-skills-travel-with-their-directory.md) 与 [ADR-0346](../adr/0346-skill-invocation-is-snapshotted-text-that-addresses-no-one.md) 定义。Host 的 `SkillCatalog` 按 Bot 分开缓存 Project 与 Host 目录:Memory Repository 下 `.agents/skills`、`.dsh/skills` 的原生文件事件只清该 Bot 的 Project 部分;DSH-native `skills/change` 是不区分 Host 与 Project 的通知:先核对已缓存 Host 目录的摘要及文件版本,只有 Host 部分确有变化才清所有 Bot 的 Host 部分并广播,避免把 Project 文件通知扩散到无关会话。监听器只递归 Skill 目录,缺失目录的创建由浅层父目录监听接续;Registry 提交后协调新增、删除与 Memory 移动,Host Plugin/Fiber dispose 关闭所有监听器及合并通知定时器。没有轮询或第二份持久化目录。

Memory 文件事件通过兼容层持有的 DSH-native Provider registration control 使原 Registry 的 cwd/scope 缓存失效;该生命周期适配 Provider 不提供 Skill 候选项,目录仍只来自 DSH 的原 Provider,查询保留原 Agent Scope。这样无需跨运行时模块实例创建 Scope 继承关系,也不调用私有缓存方法。应用定义的 `skills/catalog-changed` 通知携带 `{botSlugs, channelIds}`,复用既有 roster SSE 与 typed live stream,并按 Human 的 Channel 访问权过滤。Client action `subscribeSkillCatalog(channelId, invalidate)` 只通知相关会话,在重连 baseline 时补读;`skillCatalog(channelId)` 与 CLI `skills-list` 共用 `channelSkillCatalog`。React composer 的订阅接线由 UI 切片完成。

性能边界:无变更时 RPC 复用每 Bot 的目录;文件事件按 Bot 合并 25 ms 后推送,重算仍为按需。无范围的 DSH 通知只核对已缓存视图的 Host 摘要与文件版本,无路径的 runtime Skill 使用内容散列;这项工作发生在首次 Host 读取和事件核对时。回归测试记录 `registry.list` 的 cwd,确保 Memory 失效后的 RPC 只重算该 Bot 的 Project 部分,DSH 通知核对与 Host 变更都不重算 Project,重复读取复用缓存;这不是浏览器或原生帧率验收。

## 7 · 关键边界

- 正常运行只认 explicit Session ownership;`cwd` 只可作为迁移/修复提示,不能决定 PersonaBot 身份。
Expand Down
3 changes: 3 additions & 0 deletions packages/client/src/client/actions.ts
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
import { subscribeSkillCatalog } from './messaging-defaults-live.js';
import { replyPreviewOf } from '../../../core/src/channels/reply-preview.js';
import { gitImportSource } from '../../../../apps/mobile/src/host/bot-creation.js';
import { approveWorkspaceGrantRequest } from './bridge.js';
Expand Down Expand Up @@ -1036,6 +1037,7 @@ export interface BridgeActions {
skillInvocations?: ChannelSkillInvocationToken[],
): Promise<boolean>;
skillCatalog?(channelId: string): Promise<SkillCatalogEntry[]>;
subscribeSkillCatalog?(channelId: string, listener: () => void): () => void;
submissions: {
subscribe(listener: () => void): () => void;
snapshot(channelId: string): SubmissionSnapshot | undefined;
Expand Down Expand Up @@ -3317,6 +3319,7 @@ export function createActions(
await loadSessionsFor(slug, selection);
},
allBotPreview: (channelId) => loadAllBotPreview(call, channelId),
subscribeSkillCatalog,
skillCatalog: (channelId) => loadChannelSkillCatalog(call, channelId),
validateComposerDraft: (channelId, attachments, replyTo) =>
validateComposerDraft(call, channelId, attachments, replyTo),
Expand Down
21 changes: 16 additions & 5 deletions packages/client/src/client/bot-main.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -1909,19 +1909,30 @@ function ConversationView({
}, [scopeKey, channelId, previewRoster]);
const skillCatalogMount = useMountedResource<HTMLSpanElement>(() => {
let cancelled = false;
let generation = 0;
setSkillCatalog(undefined);
const loadSkills = actions.skillCatalog;
if (
((channel?.type === 'dm' && channel.botSlug !== undefined) || channel?.type === 'group') &&
actions.skillCatalog
!((channel?.type === 'dm' && channel.botSlug !== undefined) || channel?.type === 'group') ||
loadSkills === undefined
)
void actions
.skillCatalog(channel.id)
return () => {
cancelled = true;
};
const targetId = channel.id;
const load = (): void => {
const current = ++generation;
void loadSkills(targetId)
.then((skills) => {
if (!cancelled) setSkillCatalog(skills);
if (!cancelled && current === generation) setSkillCatalog(skills);
})
.catch(() => undefined);
};
const unsubscribe = actions.subscribeSkillCatalog?.(targetId, load);
load();
return () => {
cancelled = true;
unsubscribe?.();
};
}, [scopeKey, channelId, previewRoster]);
const skillOptions: ComposerSkillOption[] = (skillCatalog ?? []).map((entry) => ({
Expand Down
15 changes: 15 additions & 0 deletions packages/client/src/client/bridge.ts
Original file line number Diff line number Diff line change
@@ -1,3 +1,7 @@
import {
skillCatalogChangeSchema,
type SkillCatalogChange,
} from '../../../core/src/skills/events.js';
import { MEMBER_METHODS } from '../../../core/src/team/member-methods.js';
import { memberPage } from './member-page.js';
import {
Expand Down Expand Up @@ -1154,6 +1158,17 @@ function parseSkillInvocations(
});
}

export function parseSkillCatalogChange(value: unknown): SkillCatalogChange | undefined {
try {
const parsed = skillCatalogChangeSchema.safeParse(
typeof value === 'string' ? JSON.parse(value) : value,
);
return parsed.success ? parsed.data : undefined;
} catch {
return undefined;
}
}

export async function loadChannelSkillCatalog(
call: BridgeCall,
channelId: string,
Expand Down
1 change: 1 addition & 0 deletions packages/client/src/client/live-snapshots.ts
Original file line number Diff line number Diff line change
Expand Up @@ -391,6 +391,7 @@ export function createTypedLive(
},
update: (frame) => {
if (frame.type === 'changed') handlers.changed();
else if (frame.type === 'skills') handlers.skills?.(frame.change);
else if (frame.type === 'attention') handlers.attention?.();
else if (frame.type === 'latest')
handlers.latest({ channelId: frame.channelId, message: frame.message });
Expand Down
57 changes: 52 additions & 5 deletions packages/client/src/client/messaging-defaults-live.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,17 @@
import {
SKILL_CATALOG_CHANGED_EVENT,
type SkillCatalogChange,
} from '../../../core/src/skills/events.js';
import { parseSkillCatalogChange } from './bridge.js';
import type { PurgedPlacement } from '../../../core/src/purge/contracts.js';
import { parseContentRedactions } from './content-redactions.js';

const skillListeners = new Map<() => void, string>();
const skillsChanged = (change?: SkillCatalogChange): void => {
for (const [listener, channelId] of [...skillListeners])
if (change === undefined || change.channelIds.includes(channelId)) listener();
};

const listeners = new Set<() => void>();
const attentionListeners = new Map<() => void, (healthy: boolean) => void>();
let rosterHealthy = false;
Expand All @@ -23,6 +34,7 @@ export interface TypedLive {
baseline(placements: PurgedPlacement[]): void;
changed(): void;
attention?(): void;
skills?(change: unknown): void;
latest(value: unknown): void;
purged(placements: PurgedPlacement[]): void;
interrupted(): void;
Expand Down Expand Up @@ -63,12 +75,16 @@ function publishLatest(value: unknown): void {

function syncTyped(): void {
if (typed === undefined) return;
if ((listeners.size || attentionListeners.size) && stopRoster === undefined)
if (
(listeners.size || attentionListeners.size || skillListeners.size) &&
stopRoster === undefined
)
stopRoster = typed.roster({
baseline(placements) {
redactions.clear();
recordPurged(placements);
notify();
skillsChanged();
attentionHealth(true);
attentionChanged();
},
Expand All @@ -77,11 +93,20 @@ function syncTyped(): void {
attentionChanged();
},
attention: attentionChanged,
skills: (value) => {
const change = parseSkillCatalogChange(value);
if (change !== undefined) skillsChanged(change);
},
latest: publishLatest,
purged: recordPurged,
interrupted: () => attentionHealth(false),
});
else if (!listeners.size && !attentionListeners.size && stopRoster !== undefined) {
else if (
!listeners.size &&
!attentionListeners.size &&
!skillListeners.size &&
stopRoster !== undefined
) {
stopRoster();
stopRoster = undefined;
rosterHealthy = false;
Expand Down Expand Up @@ -110,7 +135,7 @@ function releaseUnusedSource(): void {
syncTyped();
if (
typed === undefined
? listeners.size || attentionListeners.size || consumers.size
? listeners.size || attentionListeners.size || skillListeners.size || consumers.size
: channelConsumer !== undefined
)
return;
Expand Down Expand Up @@ -154,7 +179,7 @@ class SharedSource extends EventTarget implements ActivityEventSource {
consumers.delete(this);
if (channelConsumer === this) channelConsumer = undefined;
releaseUnusedSource();
if (listeners.size || attentionListeners.size || consumers.size) {
if (listeners.size || attentionListeners.size || skillListeners.size || consumers.size) {
try {
ensureSource();
} catch {
Expand Down Expand Up @@ -190,9 +215,15 @@ function ensureSource(): void {
next.addEventListener('roster/changed', () => {
if (source === next) notify();
});
next.addEventListener(SKILL_CATALOG_CHANGED_EVENT, (event) => {
if (source !== next || !(event instanceof MessageEvent)) return;
const change = parseSkillCatalogChange(event.data);
if (change !== undefined) skillsChanged(change);
});
next.addEventListener('open', () => {
if (source === next) {
notify();
skillsChanged();
attentionHealth(true);
attentionChanged();
}
Expand Down Expand Up @@ -266,7 +297,8 @@ export function installTypedLive(next: TypedLive): () => void {
attentionHealth(false);
activityBaseline = undefined;
sourceUrl = undefined;
if (listeners.size || attentionListeners.size || consumers.size) ensureSource();
if (listeners.size || attentionListeners.size || skillListeners.size || consumers.size)
ensureSource();
else releaseUnusedSource();
for (const consumer of [...consumers]) consumer.publish('error', undefined, 0);
};
Expand Down Expand Up @@ -384,3 +416,18 @@ export function observeHumanAttention(refresh: () => void): () => void {
stop();
};
}

export function subscribeSkillCatalog(channelId: string, listener: () => void): () => void {
skillListeners.set(listener, channelId);
try {
ensureSource();
} catch (error) {
skillListeners.delete(listener);
releaseUnusedSource();
throw error;
}
return () => {
skillListeners.delete(listener);
releaseUnusedSource();
};
}
6 changes: 5 additions & 1 deletion packages/client/test/inert-submissions.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,9 @@
import type { BridgeActions } from '../src/client/actions.js';

export const inertSubmissionActions: Pick<BridgeActions, 'submissions' | 'averageReplyPerf'> = {
export const inertSubmissionActions: Pick<
BridgeActions,
'submissions' | 'averageReplyPerf' | 'subscribeSkillCatalog'
> = {
submissions: {
subscribe: () => () => {},
snapshot: () => undefined,
Expand All @@ -11,4 +14,5 @@ export const inertSubmissionActions: Pick<BridgeActions, 'submissions' | 'averag
reconcile: async () => {},
},
averageReplyPerf: async () => undefined,
subscribeSkillCatalog: () => () => {},
};
Loading
Loading