Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

feat(desktop): make learn a built-in skill

xd-boboda5ca6173bfd
diff --git a/apps/desktop/help-knowledge/commands.md b/apps/desktop/help-knowledge/commands.md
index fe8f88c3c6..e8405619d7 100644
--- a/apps/desktop/help-knowledge/commands.md
+++ b/apps/desktop/help-knowledge/commands.md
@@ -11,8 +11,8 @@ Passing these basic checks is not a completed build: source-specific dependencie
**What's in the palette (priority order on collisions):**
-1. **Your installed skills** (highest priority) — anything in your global or project skills directory (see the Skills topic).
-2. **Built-in app commands** — `/help` (show available commands), `/clear` (clear the current session context — resets the conversation in place without creating a new session), `/cmd` (run a shell command in the working directory), `/issue` (file an issue), `/cindy-make-doctor` (check the local build environment), `/cindy-make` (start preparing a personal Cindy build), `/goal` (start a goal-driven run), `/learn`, `/workflows`, and `/jump-session`.
+1. **Your installed skills and Cindy's built-in Skills** (highest priority) — anything in your global or project skills directory, including `/cindy-skill-creator` and `/learn` when enabled (see the Skills topic).
+2. **Built-in app commands** — `/help` (show available commands), `/clear` (clear the current session context — resets the conversation in place without creating a new session), `/cmd` (run a shell command in the working directory), `/issue` (file an issue), `/cindy-make-doctor` (check the local build environment), `/cindy-make` (start preparing a personal Cindy build), `/goal` (start a goal-driven run), `/workflows`, and `/jump-session`.
3. **The agent's own commands** — e.g. `/compact`, `/agents`, `/memory` (the exact list depends on the agent; Claude Code and Codex each contribute their own).
`/issue` does not require a GitHub plugin or GitHub account. The confirmation card uses Cindy's official bot by default; if a working account is already configured under **Plugins > Cindy GitHub**, that account appears as an optional submission identity.
diff --git a/apps/desktop/help-knowledge/skills.md b/apps/desktop/help-knowledge/skills.md
index 7f00fcb972..b70576667b 100644
--- a/apps/desktop/help-knowledge/skills.md
+++ b/apps/desktop/help-knowledge/skills.md
@@ -28,12 +28,13 @@ Skills are reusable agent capabilities you package as a folder and load into you
- Type `/` in the composer to open the slash-command palette; your installed skills show up there alongside built-in and agent commands. Pick one to run it.
-**Creating a Skill from the composer:**
+**Creating or learning a Skill from the composer:**
- Cindy includes `/cindy-skill-creator`. Invoke it with a description of the Skill you want, such as `/cindy-skill-creator Create a Skill that checks release notes`. Invoking it without a description asks what you want to create.
- The current Agent creates or updates the Skill directly with its normal file tools. It does not use the `/learn` staging flow.
- Unless you request another location, new Skills go to `~/.agents/skills/<name>/`. Ask for a project-specific Skill to create it under `<working-dir>/.agents/skills/<name>/`.
-- The built-in `cindy-skill-creator` appears in the local Skill list. You can disable or enable it there; because it ships with Cindy, it cannot be uninstalled. The setting applies to new or restarted Agent sessions.
+- Cindy also includes `/learn`. Bare `/learn` distills the current task; `/learn <description>` learns from a described workflow; `/learn hub:<scope>:<slug> [instructions]` learns from a SkillHub Skill. Cindy gathers evidence, runs the distillation in a separate task, and shows a diff for review before saving the proposed Skill.
+- The built-in `cindy-skill-creator` and `learn` entries appear in the local Skill list with an Official badge. You can disable or enable either entry there; because they ship with Cindy, they cannot be uninstalled. The setting applies to new or restarted Agent sessions. Disabling `learn` also disables the **Learn this skill** action in SkillHub after the local Skill list has refreshed.
**Disabling or uninstalling a local skill (Desktop):**
diff --git a/apps/desktop/resources/system-skills/README.md b/apps/desktop/resources/system-skills/README.md
index 75428a2468..c262baaae9 100644
--- a/apps/desktop/resources/system-skills/README.md
+++ b/apps/desktop/resources/system-skills/README.md
@@ -5,4 +5,8 @@
- Source: https://github.com/openai/codex/tree/977193486dfe7a88c4dab24abeafe9b754f5b13f/codex-rs/skills/src/assets/samples/skill-creator
- License: Apache-2.0 (preserved in `cindy-skill-creator/license.txt`)
+`learn` is authored and maintained by Cindy. It starts Cindy's managed Learn
+host through the essential `cindy_helper` bridge; another client may discover
+the Skill files, but cannot run the workflow without that host capability.
+
Cindy materializes these resources into its user-data directory at startup. Do not put user-authored Skills here.
diff --git a/apps/desktop/resources/system-skills/learn/SKILL.md b/apps/desktop/resources/system-skills/learn/SKILL.md
new file mode 100644
index 0000000000..b2f175483f
--- /dev/null
+++ b/apps/desktop/resources/system-skills/learn/SKILL.md
@@ -0,0 +1,21 @@
+---
+name: learn
+description: Distill a reusable Cindy Skill from the current task, a described workflow, or a SkillHub skill through Cindy's review flow when the user invokes /learn or explicitly asks to start Learn.
+---
+
+# Learn
+
+Start Cindy's managed Learn flow. Cindy gathers relevant evidence, creates the Skill in a separate task, and presents a diff for review before saving anything to the user's Skills directory.
+
+Do not create or edit Skill files directly as a substitute for this flow.
+
+Parse the invocation text after `/learn` (or Pi's `/skill:learn` runtime alias) and call `cindy_helper` → `call_tool` once with `name: "start_skill_learning"`:
+
+- With no text, pass `source_kind: "session"` and `input: ""`.
+- For `hub:<slug> [instructions]`, pass `source_kind: "hub"`, `hub_slug: <slug>`, `hub_catalog_scope: "market"`, and the remaining text as `input`.
+- For `hub:<market|team>:<slug> [instructions]`, use the stated `hub_catalog_scope`.
+- Otherwise pass `source_kind: "freetext"` and the full remaining text as `input`.
+
+Do not pass a task ID, working directory, or output path. Cindy binds the current task and owns staging, review, and installation.
+
+After a successful call, briefly tell the user that Learn started and that progress and review will appear in Cindy. Do not poll or call the tool again. If the helper or tool is unavailable, say that this Skill requires Cindy's Learn host; do not bypass its review flow by writing Skill files directly.
diff --git a/apps/desktop/resources/system-skills/learn/agents/openai.yaml b/apps/desktop/resources/system-skills/learn/agents/openai.yaml
new file mode 100644
index 0000000000..25df81b144
--- /dev/null
+++ b/apps/desktop/resources/system-skills/learn/agents/openai.yaml
@@ -0,0 +1,5 @@
+interface:
+ display_name: "Learn"
+ short_description: "Distill a reusable Skill with Cindy"
+policy:
+ allow_implicit_invocation: false
diff --git a/apps/desktop/src/main/bootstrap-electron.ts b/apps/desktop/src/main/bootstrap-electron.ts
index 8f50817f2c..c812c72d1e 100644
--- a/apps/desktop/src/main/bootstrap-electron.ts
+++ b/apps/desktop/src/main/bootstrap-electron.ts
@@ -1046,7 +1046,7 @@ import {
resetGoalController,
getGoalTeardownGeneration,
} from './goal-host/index.js';
-import { startLearnHost, getLearnController, resetLearnController } from './learn-host/index.js';
+import { startLearnHost, resetLearnController } from './learn-host/index.js';
import { fetchHubSkillReference } from './learn-host/hubReference.js';
import { registerLearnIpc, broadcastLearnEvent } from './learn-host/registerIpc.js';
import { registerGoalHandlers, broadcastGoalStatus } from './maker-ipc/goal.js';
@@ -6091,20 +6091,19 @@ const registerIpcHandlers = () => {
// Desktop slash command registry —— 注册 /help /clear 等内置项,
// IPC 暴露见 maker-ipc/desktop-commands.ts (待 Step 5 添加)。
// 单例 + 幂等保护 (makerIpcsRegistered flag) 保证 builtins 只灌一次。
- // remoteInvoke:远程会话(ctx.deviceId)的 /goal /learn /cmd 业务体经隧道路由
+ // remoteInvoke:远程会话(ctx.deviceId)的 /goal /cmd 业务体经隧道路由
// 到被控端 —— 走与 renderer deviceLink.invoke 同一条 handleInvoke 主路径
// (控制开关校验 + 错误映射一致)。
registerBuiltinDesktopCommands(getDesktopCommandRegistry(), {
getGoalController,
- getLearnController,
remoteInvoke: (deviceId, channel, args) =>
deviceLinkHandleInvoke(deviceLinkIpcDeps(), deviceId, channel, args),
});
// desktop-cmd:run —— /cmd 的被控端远程执行 handler(仅隧道 dispatch 消费,
// 本机 /cmd 仍在 builtins 内联执行,不走 IPC 往返)。
registerRemoteCmdIpc();
- // learn:* handler 提前一次性注册(eager,同 goal);handler 内部 getLearnController()
- // 取单例,invoke 时 controller 已由 startLearnHost 启动。
+ // learn:* handler 提前一次性注册(eager,同 goal);handler 内部读取 controller
+ // 单例,invoke 时 controller 已由 startLearnHost 启动。
registerLearnIpc();
// maker:schedule:* handler 提前一次性注册;handler 内部 awaitReady 等真实
// scheduler 实例(由后续 attemptStartScheduler 通过 attachSchedulerEventListeners
diff --git a/apps/desktop/src/main/commands/__tests__/builtinsRemoteRouting.test.ts b/apps/desktop/src/main/commands/__tests__/builtinsRemoteRouting.test.ts
index c81eb50dc4..b10b3f4a0a 100644
--- a/apps/desktop/src/main/commands/__tests__/builtinsRemoteRouting.test.ts
+++ b/apps/desktop/src/main/commands/__tests__/builtinsRemoteRouting.test.ts
@@ -2,10 +2,9 @@
* builtinsRemoteRouting.test.ts
* ---------------------------------------------------------------------------
* desktop 命令按会话归属路由的回归:ctx.deviceId 存在(device-link 远程会话)时,
- * /goal /learn /cmd 的业务体必须经 deps.remoteInvoke 隧道到被控端对应 channel,
+ * /goal /cmd 的业务体必须经 deps.remoteInvoke 隧道到被控端对应 channel,
* 且**不**触碰本机 controller;本机会话(无 deviceId)行为与改造前一致。
- * 错误分类:隧道 `[CODE] message` 编码与本机 err.code 收敛到同一套
- * (LEARN_BUSY → learn-busy;CHANNEL_NOT_ALLOWED/NOT_FOUND → remote-unsupported)。
+ * 错误分类:隧道 `[CODE] message` 编码与本机 err.code 收敛到同一套。
*/
import { describe, it, expect, vi, beforeEach } from 'vitest';
@@ -41,14 +40,12 @@ function makeHarness(overrides?: {
}) {
const registry = new DesktopCommandRegistry();
const goalController = { setGoal: vi.fn(), clearGoal: vi.fn() };
- const learnController = { startLearn: vi.fn(async () => ({ runId: 'local-run' })) };
const remoteInvoke = vi.fn(overrides?.remoteInvoke ?? (async () => ({})));
registerBuiltinDesktopCommands(registry, {
getGoalController: () => goalController as never,
- getLearnController: () => learnController as never,
remoteInvoke,
});
- return { registry, goalController, learnController, remoteInvoke };
+ return { registry, goalController, remoteInvoke };
}
beforeEach(() => {
@@ -64,6 +61,7 @@ describe('/cindy-make composer entry', () => {
description: expect.stringContaining('/cindy-make'),
});
expect(registry.list().some((command) => command.name === 'cindy-maker')).toBe(false);
+ expect(registry.list().some((command) => command.name === 'learn')).toBe(false);
});
it.each([undefined, 'remote-device'])(
@@ -116,68 +114,6 @@ describe('/goal 远程路由', () => {
});
});
-describe('/learn 远程路由', () => {
- it('deviceId → 隧道 learn:start(req 原样),runId 回灌 payload', async () => {
- const { registry, learnController, remoteInvoke } = makeHarness({
- remoteInvoke: async () => ({ runId: 'remote-run' }),
- });
- await registry.execute('learn', { sessionId: 'rs', deviceId: 'dev-1', args: '学习 X 工作流' });
- expect(remoteInvoke).toHaveBeenCalledWith('dev-1', 'learn:start', [
- { input: '学习 X 工作流', sourceKind: 'freetext', originSessionId: 'rs' },
- ]);
- expect(learnController.startLearn).not.toHaveBeenCalled();
- expect(sentPayloads().at(-1)).toMatchObject({ command: 'learn', learnRunId: 'remote-run' });
- });
-
- it('deviceId + hub:<slug> → sourceKind hub 原样隧道', async () => {
- const { remoteInvoke, registry } = makeHarness({
- remoteInvoke: async () => ({ runId: 'r2' }),
- });
- await registry.execute('learn', { sessionId: 'rs', deviceId: 'dev-1', args: 'hub:my-skill 精简点' });
- expect(remoteInvoke).toHaveBeenCalledWith('dev-1', 'learn:start', [
- { input: '精简点', sourceKind: 'hub', hubSlug: 'my-skill', originSessionId: 'rs' },
- ]);
- });
-
- it('deviceId + hub:<scope>:<slug> → 保留目录作用域', async () => {
- const { remoteInvoke, registry } = makeHarness({
- remoteInvoke: async () => ({ runId: 'r-scope' }),
- });
- await registry.execute('learn', { sessionId: 'rs', deviceId: 'dev-1', args: 'hub:team:my-skill 精简点' });
- expect(remoteInvoke).toHaveBeenCalledWith('dev-1', 'learn:start', [
- {
- input: '精简点',
- sourceKind: 'hub',
- hubSlug: 'my-skill',
- hubCatalogScope: 'team',
- originSessionId: 'rs',
- },
- ]);
- });
-
- it('隧道 [LEARN_BUSY] 编码 → learn-busy(与本机 err.code 同分类)', async () => {
- const { registry } = makeHarness({
- remoteInvoke: async () => {
- throw new Error('[LEARN_BUSY] another run in progress');
- },
- });
- await registry.execute('learn', { sessionId: 'rs', deviceId: 'dev-1', args: 'x' });
- expect(sentPayloads().at(-1)).toMatchObject({ command: 'learn', error: 'learn-busy' });
- });
-
- it('本机会话仍走本机 controller.startLearn', async () => {
- const { registry, learnController, remoteInvoke } = makeHarness();
- await registry.execute('learn', { sessionId: 'ls', args: '学习 Y' });
- expect(learnController.startLearn).toHaveBeenCalledWith({
- input: '学习 Y',
- sourceKind: 'freetext',
- originSessionId: 'ls',
- });
- expect(remoteInvoke).not.toHaveBeenCalled();
- expect(sentPayloads().at(-1)).toMatchObject({ command: 'learn', learnRunId: 'local-run' });
- });
-});
-
describe('/cmd 远程路由', () => {
it('deviceId → 隧道 desktop-cmd:run,结果回灌 /cmd 卡', async () => {
const remoteResult = {
diff --git a/apps/desktop/src/main/commands/builtins.ts b/apps/desktop/src/main/commands/builtins.ts
index 7c720c5854..710f752583 100644
--- a/apps/desktop/src/main/commands/builtins.ts
+++ b/apps/desktop/src/main/commands/builtins.ts
@@ -26,10 +26,9 @@ import { resolveMakeRuntime } from '../cindy-make/runtimeVersion.js';
import { makeToolRoot } from '../cindy-make/toolInstaller.js';
import { makeSourceRoot, prepareCindySource } from '../cindy-make/sourcePreparation.js';
import type { MakeDoctorReport } from '../../shared/cindyMakeDoctor.js';
-// type-only:不引入对 goal-host / learn-host 的运行时依赖(避免潜在 import 环),
-// 运行时实例由 bootstrap 经 deps.getGoalController / getLearnController 注入。
+// type-only:不引入对 goal-host 的运行时依赖(避免潜在 import 环),
+// 运行时实例由 bootstrap 经 deps.getGoalController 注入。
import type { GoalController } from '../goal-host/controller.js';
-import type { LearnController } from '../learn-host/controller.js';
import type { DesktopCommandContext, DesktopCommandRegistry } from './registry.js';
const log = createLogger('desktop-commands');
@@ -51,7 +50,6 @@ export interface DesktopCommandTriggeredPayload {
| 'jump-session'
| 'goal'
| 'workflows'
- | 'learn'
| 'cindy-make-doctor'
| 'cindy-make';
doctorReport?: MakeDoctorReport;
@@ -60,14 +58,12 @@ export interface DesktopCommandTriggeredPayload {
args?: string;
/** /cmd 专用 —— shell 命令执行结果。其它命令此字段不存在。 */
result?: CmdExecutionResult;
- /** /goal、/learn 共用 —— 错误码(renderer 据此显示用法/错误提示):
- * goal-usage / goal-no-session / goal-failed;learn-usage / learn-busy / learn-failed;
+ /** /goal 专用 —— 错误码(renderer 据此显示用法/错误提示):
+ * goal-usage / goal-no-session / goal-failed;
* remote-unsupported(远程会话:被控端版本过旧,不支持该命令的隧道 channel)。 */
error?: string;
/** /goal 专用 —— 动作:'set'(已设目标)/ 'cleared'(已清除)/ 'open-dialog'(无参 /goal → renderer 打开新建目标弹窗)。GoalIndicator 由状态 push 驱动,set/cleared 仅用于插一张确认卡。 */
goalAction?: 'set' | 'cleared' | 'open-dialog';
- /** /learn 专用 —— 启动成功时的 runId(renderer 据此关联 learn:event 状态流)。 */
- learnRunId?: string;
}
export interface CmdExecutionResult {
@@ -340,11 +336,9 @@ const GOAL_CLEAR_ALIASES = new Set(['clear', 'stop', 'off', 'cancel', 'reset', '
export interface BuiltinDesktopCommandDeps {
/** null-safe 取 GoalController 单例(注册早于 startGoalController,invoke 时已就绪)。 */
getGoalController: () => GoalController | null;
- /** null-safe 取 LearnController 单例(同 goal:注册早于 startLearnHost)。 */
- getLearnController: () => LearnController | null;
/**
* device-link 隧道 invoke(控制端 → 被控端)。ctx.deviceId 存在(远程会话)时,
- * /goal /learn /cmd 的业务体经它路由到被控端执行 —— 与 renderer 的
+ * /goal /cmd 的业务体经它路由到被控端执行 —— 与 renderer 的
* deviceLink.invoke 走同一条 handleInvoke 主路径(含控制开关校验 + 错误映射,
* 失败抛 `[CODE] message` 形态 Error)。bootstrap 注入,避免 builtins 直接
* import device-link 运行时(与 getGoalController 同款解耦)。
@@ -353,7 +347,7 @@ export interface BuiltinDesktopCommandDeps {
}
/**
- * 从错误对象提取错误码:优先取 `.code`(本机 LearnError / GoalControllerInputError),
+ * 从错误对象提取错误码:优先取 `.code`(本机 GoalControllerInputError),
* 回退解析 throwIpcError 的 `[CODE] message` 编码(隧道透传的被控端错误)。
* 本机与远程两条错误链路因此在调用点收敛成同一套分类逻辑。
*/
@@ -691,64 +685,6 @@ export function registerBuiltinDesktopCommands(
},
});
- registry.register({
- name: 'learn',
- description:
- 'Distill a reusable skill from anything you describe (a workflow, a repo, a URL, how you usually do X) — grounded in your usage history and profile, reviewed as a diff before saving. Bare /learn distills the current conversation; /learn hub:<slug> learns from a SkillHub skill. Usage: /learn [hub:<slug>] [what to learn]',
- execute: async (ctx) => {
- const arg = (ctx.args ?? '').trim();
- // 无参 /learn = 蒸馏当前会话(Hermes 同语义)—— 需要挂在一个已有会话上;
- // 草稿态(无 sessionId)没有可蒸的内容,回用法提示。
- if (!arg && !ctx.sessionId) {
- sendDesktopCommandToSender(ctx, { ...buildPayload('learn', ctx), error: 'learn-usage' });
- return;
- }
- // 远程会话:learn-host 全流程在被控端(证据查它自己的 DB、staging 在它的
- // userData、skill 落它的 ~/.agents/skills),startLearn 经隧道路由到
- // learn:start;本机路径不变。
- const controller = ctx.deviceId ? null : deps.getLearnController();
- if (!ctx.deviceId && !controller) {
- sendDesktopCommandToSender(ctx, { ...buildPayload('learn', ctx), error: 'learn-failed' });
- return;
- }
- // `/learn hub:<slug> [补充要求]` —— skill hub「学习此技能」预填的形态,
- // 用户可在输入框改要求、换模型后再发。slug 规则与市场一致([a-z0-9-])。
- const hubMatch = /^hub:(?:(market|team):)?([a-z0-9][a-z0-9-]*)\s*/.exec(arg);
- const req = hubMatch
- ? {
- input: arg.slice(hubMatch[0].length).trim(),
- sourceKind: 'hub' as const,
- hubSlug: hubMatch[2],
- ...(hubMatch[1] ? { hubCatalogScope: hubMatch[1] as 'market' | 'team' } : {}),
- ...(ctx.sessionId ? { originSessionId: ctx.sessionId } : {}),
- }
- : {
- input: arg,
- sourceKind: (arg ? 'freetext' : 'session') as 'freetext' | 'session',
- ...(ctx.sessionId ? { originSessionId: ctx.sessionId } : {}),
- };
- try {
- const { runId } = ctx.deviceId
- ? ((await deps.remoteInvoke(ctx.deviceId, 'learn:start', [req])) as { runId: string })
- : await controller!.startLearn(req);
- sendDesktopCommandToSender(ctx, { ...buildPayload('learn', ctx), learnRunId: runId });
- } catch (err) {
- // extractErrorCode 同时覆盖本机 LearnError.code 与隧道 `[LEARN_BUSY] ...` 编码。
- const code = extractErrorCode(err);
- log.warn('/learn startLearn failed', err);
- sendDesktopCommandToSender(ctx, {
- ...buildPayload('learn', ctx),
- error:
- code === 'LEARN_BUSY'
- ? 'learn-busy'
- : isRemoteUnsupported(err)
- ? 'remote-unsupported'
- : 'learn-failed',
- });
- }
- },
- });
-
registry.register({
name: 'workflows',
description:
diff --git a/apps/desktop/src/main/learn-host/controller.ts b/apps/desktop/src/main/learn-host/controller.ts
index e82c72a7b9..5bec10112c 100644
--- a/apps/desktop/src/main/learn-host/controller.ts
+++ b/apps/desktop/src/main/learn-host/controller.ts
@@ -333,7 +333,7 @@ export class LearnController {
throw new LearnError('INVALID_PARAMS', 'hubSlug is required for hub source');
}
// hubSlug 会作为路径段进入 resolveInstalledSkillDir / writeReferenceFiles:
- // builtins 的 /learn hub: 正则已限,但 IPC learn:start 可直调 —— 边界处再校
+ // 内置 Skill 与 IPC learn:start 都可能传入 hubSlug —— 在状态机边界再校
// 一次,拒绝分隔符 / '..' 等任意串(自查;与市场 slug 规则一致)。
if (req.sourceKind === 'hub' && req.hubSlug && !/^[a-z0-9][a-z0-9-]*$/.test(req.hubSlug)) {
throw new LearnError('INVALID_PARAMS', `invalid hubSlug: ${req.hubSlug}`);
diff --git a/apps/desktop/src/main/learn-host/index.ts b/apps/desktop/src/main/learn-host/index.ts
index fc2e304605..428a228948 100644
--- a/apps/desktop/src/main/learn-host/index.ts
+++ b/apps/desktop/src/main/learn-host/index.ts
@@ -207,9 +207,20 @@ export function startLearnHost(deps: StartLearnHostDeps): LearnController {
.orderBy(desc(messagesTable.createdAt))
.limit(CONVERSATION_MESSAGE_LIMIT);
const items: Array<{ role: string; text: string }> = [];
- for (const r of rows.reverse()) {
+ const chronologicalRows = rows.reverse();
+ for (const [index, r] of chronologicalRows.entries()) {
const text = visibleMessageTextForConversationSearch(r.role, r.content);
if (!text) continue;
+ // The built-in Learn Skill reaches the host after its invocation has
+ // entered chat history. Keep the trigger itself out of the evidence;
+ // the former Desktop command was intercepted before persistence.
+ if (
+ index === chronologicalRows.length - 1
+ && r.role === 'user'
+ && /^\/(?:skill:)?learn\s*$/i.test(text.trim())
+ ) {
+ continue;
+ }
items.push({ role: r.role, text: redactSensitive(text).text });
}
return formatConversationBlock(items);
@@ -312,7 +323,7 @@ export function startLearnHost(deps: StartLearnHostDeps): LearnController {
return controller;
}
-/** null-safe 取单例 —— startLearnHost 之前调用返回 null(builtins /learn 用)。 */
+/** null-safe 取单例 —— startLearnHost 之前调用返回 null(cindy_helper Learn 工具使用)。 */
export function getLearnController(): LearnController | null {
return _controller;
}
diff --git a/apps/desktop/src/main/maker-host/__tests__/built-in-skills.test.ts b/apps/desktop/src/main/maker-host/__tests__/built-in-skills.test.ts
index 46a46fc09b..7e702b71c7 100644
--- a/apps/desktop/src/main/maker-host/__tests__/built-in-skills.test.ts
+++ b/apps/desktop/src/main/maker-host/__tests__/built-in-skills.test.ts
@@ -16,14 +16,20 @@ function fixture() {
roots.push(root);
const bundledRoot = path.join(root, 'resources', 'system-skills');
const source = path.join(bundledRoot, 'cindy-skill-creator');
+ const learnSource = path.join(bundledRoot, 'learn');
const userDataDir = path.join(root, 'user-data');
const homeDir = path.join(root, 'home');
fs.mkdirSync(path.join(source, 'scripts'), { recursive: true });
+ fs.mkdirSync(learnSource, { recursive: true });
fs.writeFileSync(
path.join(source, 'SKILL.md'),
'---\nname: cindy-skill-creator\ndescription: Create Skills\n---\n\n# Creator\n',
);
fs.writeFileSync(path.join(source, 'scripts', 'validate.py'), 'print("ok")\n');
+ fs.writeFileSync(
+ path.join(learnSource, 'SKILL.md'),
+ '---\nname: learn\ndescription: Start Cindy Learn\n---\n\n# Learn\n',
+ );
return { bundledRoot, source, userDataDir, homeDir };
}
@@ -46,6 +52,13 @@ describe('built-in Skills', () => {
expect(fs.readFileSync(path.join(descriptor.absolutePath, 'SKILL.md'), 'utf8')).toContain(
'# Creator',
);
+ const learnDescriptor = first.descriptors.find((item) => item.name === 'learn')!;
+ expect(fs.realpathSync(path.join(input.homeDir, '.agents', 'skills', 'learn'))).toBe(
+ fs.realpathSync(learnDescriptor.absolutePath),
+ );
+ expect(fs.readFileSync(path.join(learnDescriptor.absolutePath, 'SKILL.md'), 'utf8')).toContain(
+ '# Learn',
+ );
const second = await prepareBuiltInSkills(input);
expect(second.changed).toBe(false);
diff --git a/apps/desktop/src/main/maker-host/built-in-skills.ts b/apps/desktop/src/main/maker-host/built-in-skills.ts
index 921a16ec2e..0bfbd6ef34 100644
--- a/apps/desktop/src/main/maker-host/built-in-skills.ts
+++ b/apps/desktop/src/main/maker-host/built-in-skills.ts
@@ -3,12 +3,16 @@ import fs from 'node:fs';
import { promises as fsp } from 'node:fs';
import os from 'node:os';
import path from 'node:path';
-import { CINDY_SKILL_CREATOR_NAME } from '../../shared/cindyBuiltInSkills';
+import {
+ CINDY_LEARN_NAME,
+ CINDY_SKILL_CREATOR_NAME,
+} from '../../shared/cindyBuiltInSkills';
import { atomicWriteFileSync } from '../utils/atomicWriteFile';
export const BUILT_IN_SKILL_CREATOR_NAME = CINDY_SKILL_CREATOR_NAME;
+export const BUILT_IN_LEARN_SKILL_NAME = CINDY_LEARN_NAME;
-const BUILT_IN_SKILL_NAMES = [BUILT_IN_SKILL_CREATOR_NAME] as const;
+const BUILT_IN_SKILL_NAMES = [BUILT_IN_SKILL_CREATOR_NAME, BUILT_IN_LEARN_SKILL_NAME] as const;
const MANIFEST_FILE = '.cindy-system-skills.json';
export interface BuiltInSkillDescriptor {
diff --git a/apps/desktop/src/main/maker-ipc/helpKnowledge.generated.ts b/apps/desktop/src/main/maker-ipc/helpKnowledge.generated.ts
index ed927344b5..16e9c64552 100644
--- a/apps/desktop/src/main/maker-ipc/helpKnowledge.generated.ts
+++ b/apps/desktop/src/main/maker-ipc/helpKnowledge.generated.ts
@@ -34,7 +34,7 @@ export const HELP_KNOWLEDGE: HelpKnowledgeDoc[] = [
id: "commands",
title: "Slash commands",
summary: "Type \"/\" in the composer to open a palette merging your skills, built-in app commands, and the agent's own commands.",
- content: "Type `/` at the start of the composer to open the command palette.\n\n`/cindy-make-doctor` checks the local Desktop environment without involving an Agent. An expandable card in the current task's message stream shows system/architecture, Git, Git LFS, Node.js, pnpm, Python, native build tools, and available space/write permissions in Cindy's data directory. Progress and rechecks update the same card in place. From the home page, Cindy creates a local task to display the card, without sending a message to an Agent. Compatible existing tools are reused. The check does not install tools, download source, query upstream Issues/PRs, or require a GitHub account. It can be stopped and rerun; results are temporary and are not saved to task history across restarts. Use it on the local Desktop; SSH, device-link, and Mobile entry are not supported in this stage.\n\nPassing these basic checks is not a completed build: source-specific dependencies and packaging prerequisites will be checked in the later build workflow. `/cindy-make` reuses this diagnostic capability as its first step.\n\n**What's in the palette (priority order on collisions):**\n\n1. **Your installed skills** (highest priority) — anything in your global or project skills directory (see the Skills topic).\n2. **Built-in app commands** — `/help` (show available commands), `/clear` (clear the current session context — resets the conversation in place without creating a new session), `/cmd` (run a shell command in the working directory), `/issue` (file an issue), `/cindy-make-doctor` (check the local build environment), `/cindy-make` (start preparing a personal Cindy build), `/goal` (start a goal-driven run), `/learn`, `/workflows`, and `/jump-session`.\n3. **The agent's own commands** — e.g. `/compact`, `/agents`, `/memory` (the exact list depends on the agent; Claude Code and Codex each contribute their own).\n\n`/issue` does not require a GitHub plugin or GitHub account. The confirmation card uses Cindy's official bot by default; if a working account is already configured under **Plugins > Cindy GitHub**, that account appears as an optional submission identity.\n\nBefore submitting, Cindy helps clarify missing details so the issue is actionable. For bugs, it can collect reproduction steps and user-approved, redacted diagnostic summaries; the confirmation card always shows the final public content. After creation, Cindy returns the issue link and can help interested users reproduce or fix the problem from source because Cindy is open source.\n\n`/cindy-make [request]` uses one expandable card in the current task's message stream: **1. Prepare environment → 2. Check upstream**. The request must be supplied after the command; a bare `/cindy-make` only shows usage guidance and does not create a card or start environment checks. It first reuses compatible system tools or previously installed Cindy-managed tools, then downloads and installs missing portable tools. Every required environment check must pass before it automatically searches public Issues and PRs in `makecindy/cindy`. From home, Cindy creates only a local task to hold the card. No model connection or Agent turn is required. Only the explicit slash command starts the workflow; ordinary messages are unaffected, and a same-name Skill retains priority. This stage accepts plain text, not attachments, references or comments. Use it on the local Desktop; SSH, device-link and Mobile entry are not supported.\n\nPortable Node.js, pnpm, Python and Git LFS packages are selected for Windows x64, macOS x64/arm64 and Linux x64/arm64 (glibc). Windows can also install portable MinGit. macOS Git comes with Xcode Command Line Tools; Linux Git comes from the distribution's package manager. Missing system compilers (Visual Studio C++ Build Tools and Windows SDK, Xcode Command Line Tools, or Linux C/C++ tools) show installation instructions in the card. Cindy does not run admin commands or install global tools. At least 2 GiB of free space is required to provision tools; at least 10 GiB is recommended before a build. OS/ABI compatibility is verified by starting each staged tool; a failure is shown for manual installation or retry.\n\nDownloads come from pinned publisher URLs and must pass SHA-256 verification before extraction or execution. Tools are installed under the `cindy-make` subdirectory of Cindy's data directory. Completed tools persist and are reused after restart; failed or cancelled attempts never replace a working tool. Global PATH and Git configuration stay unchanged. `/cindy-make-doctor` can check these managed tools but never installs anything itself.\n\nThe card shows download progress and offers Stop while preparing or searching, then Retry after a problem or cancellation. Progress and retries update the same message and keep the request. Successful installs are rechecked automatically; no extra click is needed to start upstream search. Only one preparation/search runs at a time. There is no Back button; rechecking runs the environment checks again before another search and reuses already-installed tools.\n\nUpstream search uses up to three literal keywords extracted from the request and shows those keywords with up to five possible matches. This is a keyword search, not a guarantee of semantic similarity or an exhaustive search. Each result includes its link, number, title, Issue/PR kind, state, and available author, update date and body excerpt. Closed PRs are checked for merge status; if verification fails, that status is explicitly unverified. A closed Issue is not necessarily fixed, and a merged PR is not necessarily in an official release. A successful search with no matches says so; network errors, rate limits and timeouts are shown as failures, never as no matches.\n\nAfter a successful search, choose **Wait for upstream** or **Continue with a personal version**. Waiting does not subscribe to notifications or enable automatic updates. Choosing a personal version starts a managed source checkout after the environment is ready: dev follows `main`; beta and release use the matching `vX.Y.Z` tag, with the matching `-beta` tag as the fallback. A missing pair of tags stops with an error, and a managed checkout with local changes is never overwritten. Checks, request text, results and the choice are temporary and disappear when the app reloads or restarts. No GitHub account is required.\n\n**Settings > Cindy Make** runs the same read-only environment check whenever the page opens, with a manual recheck action and an **Open tools directory** button inside the card. Missing portable tools can be installed from the card. This page and `/cindy-make-doctor` remain environment-only; neither starts upstream search. In development builds, **Test Installation: Ignore System Tools** checks portable tools using only Cindy-managed copies and simulates missing Windows native compiler prerequisites so their official installation guide can be tested. System Git and compiler prerequisites on macOS/Linux are checked normally. Turning the switch on only rechecks; click the install button to install missing tools. Completed managed installs are reused. The switch applies immediately within the current window and resets on reload/restart. Packaged builds do not expose or accept this test option. Both checks and preparation cards label results produced with the test switch on.\n\n**Using the palette:**\n\n- Start typing to filter. Matching is **contains-based** (case-insensitive substring matching on the command name) — not fuzzy.\n- Up to 25 matches shown at a time.\n- **↑ / ↓** move focus, **Enter** runs the focused command, **Esc** closes the palette.\n\n**Notes:**\n\n- If a name collides across sources (same command in a skill and in a built-in), the higher-priority source wins; the lower-priority one is silently skipped (logged as a warning).\n- Most built-in app commands run inside the desktop app (a few, like `/workflows` and `/jump-session`, are handled directly in the UI); agent commands are sent as prompt prefixes to the agent.",
+ content: "Type `/` at the start of the composer to open the command palette.\n\n`/cindy-make-doctor` checks the local Desktop environment without involving an Agent. An expandable card in the current task's message stream shows system/architecture, Git, Git LFS, Node.js, pnpm, Python, native build tools, and available space/write permissions in Cindy's data directory. Progress and rechecks update the same card in place. From the home page, Cindy creates a local task to display the card, without sending a message to an Agent. Compatible existing tools are reused. The check does not install tools, download source, query upstream Issues/PRs, or require a GitHub account. It can be stopped and rerun; results are temporary and are not saved to task history across restarts. Use it on the local Desktop; SSH, device-link, and Mobile entry are not supported in this stage.\n\nPassing these basic checks is not a completed build: source-specific dependencies and packaging prerequisites will be checked in the later build workflow. `/cindy-make` reuses this diagnostic capability as its first step.\n\n**What's in the palette (priority order on collisions):**\n\n1. **Your installed skills and Cindy's built-in Skills** (highest priority) — anything in your global or project skills directory, including `/cindy-skill-creator` and `/learn` when enabled (see the Skills topic).\n2. **Built-in app commands** — `/help` (show available commands), `/clear` (clear the current session context — resets the conversation in place without creating a new session), `/cmd` (run a shell command in the working directory), `/issue` (file an issue), `/cindy-make-doctor` (check the local build environment), `/cindy-make` (start preparing a personal Cindy build), `/goal` (start a goal-driven run), `/workflows`, and `/jump-session`.\n3. **The agent's own commands** — e.g. `/compact`, `/agents`, `/memory` (the exact list depends on the agent; Claude Code and Codex each contribute their own).\n\n`/issue` does not require a GitHub plugin or GitHub account. The confirmation card uses Cindy's official bot by default; if a working account is already configured under **Plugins > Cindy GitHub**, that account appears as an optional submission identity.\n\nBefore submitting, Cindy helps clarify missing details so the issue is actionable. For bugs, it can collect reproduction steps and user-approved, redacted diagnostic summaries; the confirmation card always shows the final public content. After creation, Cindy returns the issue link and can help interested users reproduce or fix the problem from source because Cindy is open source.\n\n`/cindy-make [request]` uses one expandable card in the current task's message stream: **1. Prepare environment → 2. Check upstream**. The request must be supplied after the command; a bare `/cindy-make` only shows usage guidance and does not create a card or start environment checks. It first reuses compatible system tools or previously installed Cindy-managed tools, then downloads and installs missing portable tools. Every required environment check must pass before it automatically searches public Issues and PRs in `makecindy/cindy`. From home, Cindy creates only a local task to hold the card. No model connection or Agent turn is required. Only the explicit slash command starts the workflow; ordinary messages are unaffected, and a same-name Skill retains priority. This stage accepts plain text, not attachments, references or comments. Use it on the local Desktop; SSH, device-link and Mobile entry are not supported.\n\nPortable Node.js, pnpm, Python and Git LFS packages are selected for Windows x64, macOS x64/arm64 and Linux x64/arm64 (glibc). Windows can also install portable MinGit. macOS Git comes with Xcode Command Line Tools; Linux Git comes from the distribution's package manager. Missing system compilers (Visual Studio C++ Build Tools and Windows SDK, Xcode Command Line Tools, or Linux C/C++ tools) show installation instructions in the card. Cindy does not run admin commands or install global tools. At least 2 GiB of free space is required to provision tools; at least 10 GiB is recommended before a build. OS/ABI compatibility is verified by starting each staged tool; a failure is shown for manual installation or retry.\n\nDownloads come from pinned publisher URLs and must pass SHA-256 verification before extraction or execution. Tools are installed under the `cindy-make` subdirectory of Cindy's data directory. Completed tools persist and are reused after restart; failed or cancelled attempts never replace a working tool. Global PATH and Git configuration stay unchanged. `/cindy-make-doctor` can check these managed tools but never installs anything itself.\n\nThe card shows download progress and offers Stop while preparing or searching, then Retry after a problem or cancellation. Progress and retries update the same message and keep the request. Successful installs are rechecked automatically; no extra click is needed to start upstream search. Only one preparation/search runs at a time. There is no Back button; rechecking runs the environment checks again before another search and reuses already-installed tools.\n\nUpstream search uses up to three literal keywords extracted from the request and shows those keywords with up to five possible matches. This is a keyword search, not a guarantee of semantic similarity or an exhaustive search. Each result includes its link, number, title, Issue/PR kind, state, and available author, update date and body excerpt. Closed PRs are checked for merge status; if verification fails, that status is explicitly unverified. A closed Issue is not necessarily fixed, and a merged PR is not necessarily in an official release. A successful search with no matches says so; network errors, rate limits and timeouts are shown as failures, never as no matches.\n\nAfter a successful search, choose **Wait for upstream** or **Continue with a personal version**. Waiting does not subscribe to notifications or enable automatic updates. Choosing a personal version starts a managed source checkout after the environment is ready: dev follows `main`; beta and release use the matching `vX.Y.Z` tag, with the matching `-beta` tag as the fallback. A missing pair of tags stops with an error, and a managed checkout with local changes is never overwritten. Checks, request text, results and the choice are temporary and disappear when the app reloads or restarts. No GitHub account is required.\n\n**Settings > Cindy Make** runs the same read-only environment check whenever the page opens, with a manual recheck action and an **Open tools directory** button inside the card. Missing portable tools can be installed from the card. This page and `/cindy-make-doctor` remain environment-only; neither starts upstream search. In development builds, **Test Installation: Ignore System Tools** checks portable tools using only Cindy-managed copies and simulates missing Windows native compiler prerequisites so their official installation guide can be tested. System Git and compiler prerequisites on macOS/Linux are checked normally. Turning the switch on only rechecks; click the install button to install missing tools. Completed managed installs are reused. The switch applies immediately within the current window and resets on reload/restart. Packaged builds do not expose or accept this test option. Both checks and preparation cards label results produced with the test switch on.\n\n**Using the palette:**\n\n- Start typing to filter. Matching is **contains-based** (case-insensitive substring matching on the command name) — not fuzzy.\n- Up to 25 matches shown at a time.\n- **↑ / ↓** move focus, **Enter** runs the focused command, **Esc** closes the palette.\n\n**Notes:**\n\n- If a name collides across sources (same command in a skill and in a built-in), the higher-priority source wins; the lower-priority one is silently skipped (logged as a warning).\n- Most built-in app commands run inside the desktop app (a few, like `/workflows` and `/jump-session`, are handled directly in the UI); agent commands are sent as prompt prefixes to the agent.",
},
{
id: "connections",
@@ -144,7 +144,7 @@ export const HELP_KNOWLEDGE: HelpKnowledgeDoc[] = [
id: "skills",
title: "Skills (reusable agent capabilities)",
summary: "Create, browse, install, disable, uninstall, publish, and update agent Skills; Skills appear as \"/\" slash commands and are shared across Claude Code, Codex, and Pi.",
- content: "Skills are reusable agent capabilities you package as a folder and load into your sessions. They're managed on the same page as Plugins — **Skills** and **Plugins** are two tabs of one management surface (the Skills tab is the in-app browser for finding, installing, publishing, and updating skills).\n\n**Skills work across local agents:**\n\n- Skills are **engine-shared** — the same installed Skill is available to Claude Code, Codex, and Pi, so you install it once.\n\n**Where skills live on disk:**\n\n- Global (available to every session): the shared root `~/.agents/skills/<name>/`, which is cross-linked to `~/.claude/skills/` and `~/.codex/skills/` so every engine sees the same skills. On Windows that's under `C:\\Users\\<you>\\`.\n- Project-scoped (only inside one working directory): `<working-dir>/.agents/skills/<name>/` or `<working-dir>/.claude/skills/<name>/`.\n- Each skill is its own folder with a required `SKILL.md` at the root (the prompt / spec the agent reads). Sibling files and subfolders in that folder are also visible to the agent.\n\n**Importing a local skill:**\n\n- On the Skills page, use **Import skill** (top-right) to pick a `.zip` package or a standalone `SKILL.md` file.\n- A zip must contain a `SKILL.md` (at the package root, or inside a single top-level folder). The YAML frontmatter must include non-empty `name` and `description` fields; `name` must match `^[a-z0-9-]{1,200}$`.\n- You then choose where to install: global, a known project, or another directory. Cindy extracts metadata from the file automatically and lists the skill with that name and description.\n- Imported skills can be uninstalled from the detail page, and you can publish them to SkillHub later if you want.\n\n**Using an installed skill:**\n\n- Hover over a local skill in the `/` suggestions and choose **View skill details** in its information panel to open that exact skill. This does not insert or send the command. Pi package skills remain usable from `/`, but do not show this local detail shortcut; manage them through their package.\n\n- Type `/` in the composer to open the slash-command palette; your installed skills show up there alongside built-in and agent commands. Pick one to run it.\n\n**Creating a Skill from the composer:**\n\n- Cindy includes `/cindy-skill-creator`. Invoke it with a description of the Skill you want, such as `/cindy-skill-creator Create a Skill that checks release notes`. Invoking it without a description asks what you want to create.\n- The current Agent creates or updates the Skill directly with its normal file tools. It does not use the `/learn` staging flow.\n- Unless you request another location, new Skills go to `~/.agents/skills/<name>/`. Ask for a project-specific Skill to create it under `<working-dir>/.agents/skills/<name>/`.\n- The built-in `cindy-skill-creator` appears in the local Skill list. You can disable or enable it there; because it ships with Cindy, it cannot be uninstalled. The setting applies to new or restarted Agent sessions.\n\n**Disabling or uninstalling a local skill (Desktop):**\n\n- Open a skill's detail page to use the switch in the top action bar. For a market skill installed in multiple locations, select the local copy from the location dropdown beside the switch. Turning it off keeps the files and removes the skill from new-task command previews. Active tasks retain the skill preference snapshot applied when their Agent started, including their command palette. New or restarted Claude Code, Codex, and Pi agents apply that choice; an already-running agent keeps its existing context.\n- Renaming a local skill while publishing keeps its enabled or disabled setting. If renaming fails, Cindy restores the original folder and content.\n- The switch is local to this device and Cindy profile. It does not edit external CLI settings, sync to other devices, or override a native engine's own disabled state. Enable it again to let the engine discover it normally.\n- In the skill's details, use **… → Uninstall skill**. Confirm the location and shared-file impact. Standalone skills, including locally written skills without a market installation record, move to the system trash. Recovery is through the operating system's trash.\n- External source imports remove only their discovery links and keep the external source files. Package-owned Skills must be removed through their owning package. Cindy's built-in Skills cannot be uninstalled, but they can be disabled. Skills provided by Cindy plugins are managed on the owning plugin's page, including when discovered through shared Skill links.\n- Offline removal of an automatically synced skill is remembered on this device, including after restart or sign-in. Automatic sync skips it until you explicitly install it again.\n- Uninstalling a shared copy affects external CLIs that use it. It does not unpublish a skill or delete other users' copies. If file removal fails, Cindy keeps the installation. If cleanup is interrupted, the notice offers **Retry cleanup**. The unfinished operation survives closing, reloading, and restarting Cindy; reopen Skills in the same Cindy profile and account to continue. Cindy pauses conflicting installations until cleanup completes. Retrying never moves files to the trash a second time and preserves externally restored or replaced content.\n\n**Publishing your own skill:**\n\n- Find the publish action on the Skills page and point it at the skill's local folder. It zips the folder and uploads it — reading your directory in place, without copying or moving anything.\n- On first publish, you set the skill's **visibility**: PUBLIC (anyone in the org) or DEPARTMENT_SCOPED (only the departments you choose).\n- The local registry records what you published, so the app knows it's \"yours\" for future updates.\n\n**Updating an already-published skill:**\n\n- On your own skill's detail page you'll see a **发布新版本** (Publish New Version) button.\n- Edit the local folder however you want and publish — the version is **auto-incremented server-side**, you don't pick a number.\n- **Old versions stay live alongside the new one.** Users who already installed an older version keep it until they choose to update.\n- The display name and description are sent on every republish, so editing those metadata fields just means doing a republish.\n\n**Managing an already-published skill:**\n\n- Change who can see or use your skill from the management menu — public, shared with selected teams / departments, or private to you.\n- **Unpublish** makes it private again and returns ownership to your personal scope; it does not remove copies other users already installed.\n- **Authorship is fixed.** Only the original author's account can publish new versions of a given skill (enforced server-side as `NOT_AUTHOR`).\n\n**Browsing and installing others' skills:**\n\n- The marketplace lets you install skills into your global skills directory. You can request a specific version on install; the local registry tracks which version you have.\n\n**Notes:**\n\n- A skill folder without a `SKILL.md` at its root won't be picked up (lowercase `skill.md` is also accepted).\n- Project-scoped skills only show up in sessions whose working directory matches — useful for skills tied to a particular repo's conventions.\n- Editing files inside an installed skill folder takes effect on the next session start; you don't need to reinstall.\n- Uninstalling only removes your local copy. For your own published skills, use unpublish or manage visibility to change market availability.\n\nIn a new-task draft, the slash hover panel offers detail links for global skills. Project skill detail links are available after creating a task, when SkillHub can include that project in its scan.",
+ content: "Skills are reusable agent capabilities you package as a folder and load into your sessions. They're managed on the same page as Plugins — **Skills** and **Plugins** are two tabs of one management surface (the Skills tab is the in-app browser for finding, installing, publishing, and updating skills).\n\n**Skills work across local agents:**\n\n- Skills are **engine-shared** — the same installed Skill is available to Claude Code, Codex, and Pi, so you install it once.\n\n**Where skills live on disk:**\n\n- Global (available to every session): the shared root `~/.agents/skills/<name>/`, which is cross-linked to `~/.claude/skills/` and `~/.codex/skills/` so every engine sees the same skills. On Windows that's under `C:\\Users\\<you>\\`.\n- Project-scoped (only inside one working directory): `<working-dir>/.agents/skills/<name>/` or `<working-dir>/.claude/skills/<name>/`.\n- Each skill is its own folder with a required `SKILL.md` at the root (the prompt / spec the agent reads). Sibling files and subfolders in that folder are also visible to the agent.\n\n**Importing a local skill:**\n\n- On the Skills page, use **Import skill** (top-right) to pick a `.zip` package or a standalone `SKILL.md` file.\n- A zip must contain a `SKILL.md` (at the package root, or inside a single top-level folder). The YAML frontmatter must include non-empty `name` and `description` fields; `name` must match `^[a-z0-9-]{1,200}$`.\n- You then choose where to install: global, a known project, or another directory. Cindy extracts metadata from the file automatically and lists the skill with that name and description.\n- Imported skills can be uninstalled from the detail page, and you can publish them to SkillHub later if you want.\n\n**Using an installed skill:**\n\n- Hover over a local skill in the `/` suggestions and choose **View skill details** in its information panel to open that exact skill. This does not insert or send the command. Pi package skills remain usable from `/`, but do not show this local detail shortcut; manage them through their package.\n\n- Type `/` in the composer to open the slash-command palette; your installed skills show up there alongside built-in and agent commands. Pick one to run it.\n\n**Creating or learning a Skill from the composer:**\n\n- Cindy includes `/cindy-skill-creator`. Invoke it with a description of the Skill you want, such as `/cindy-skill-creator Create a Skill that checks release notes`. Invoking it without a description asks what you want to create.\n- The current Agent creates or updates the Skill directly with its normal file tools. It does not use the `/learn` staging flow.\n- Unless you request another location, new Skills go to `~/.agents/skills/<name>/`. Ask for a project-specific Skill to create it under `<working-dir>/.agents/skills/<name>/`.\n- Cindy also includes `/learn`. Bare `/learn` distills the current task; `/learn <description>` learns from a described workflow; `/learn hub:<scope>:<slug> [instructions]` learns from a SkillHub Skill. Cindy gathers evidence, runs the distillation in a separate task, and shows a diff for review before saving the proposed Skill.\n- The built-in `cindy-skill-creator` and `learn` entries appear in the local Skill list with an Official badge. You can disable or enable either entry there; because they ship with Cindy, they cannot be uninstalled. The setting applies to new or restarted Agent sessions. Disabling `learn` also disables the **Learn this skill** action in SkillHub after the local Skill list has refreshed.\n\n**Disabling or uninstalling a local skill (Desktop):**\n\n- Open a skill's detail page to use the switch in the top action bar. For a market skill installed in multiple locations, select the local copy from the location dropdown beside the switch. Turning it off keeps the files and removes the skill from new-task command previews. Active tasks retain the skill preference snapshot applied when their Agent started, including their command palette. New or restarted Claude Code, Codex, and Pi agents apply that choice; an already-running agent keeps its existing context.\n- Renaming a local skill while publishing keeps its enabled or disabled setting. If renaming fails, Cindy restores the original folder and content.\n- The switch is local to this device and Cindy profile. It does not edit external CLI settings, sync to other devices, or override a native engine's own disabled state. Enable it again to let the engine discover it normally.\n- In the skill's details, use **… → Uninstall skill**. Confirm the location and shared-file impact. Standalone skills, including locally written skills without a market installation record, move to the system trash. Recovery is through the operating system's trash.\n- External source imports remove only their discovery links and keep the external source files. Package-owned Skills must be removed through their owning package. Cindy's built-in Skills cannot be uninstalled, but they can be disabled. Skills provided by Cindy plugins are managed on the owning plugin's page, including when discovered through shared Skill links.\n- Offline removal of an automatically synced skill is remembered on this device, including after restart or sign-in. Automatic sync skips it until you explicitly install it again.\n- Uninstalling a shared copy affects external CLIs that use it. It does not unpublish a skill or delete other users' copies. If file removal fails, Cindy keeps the installation. If cleanup is interrupted, the notice offers **Retry cleanup**. The unfinished operation survives closing, reloading, and restarting Cindy; reopen Skills in the same Cindy profile and account to continue. Cindy pauses conflicting installations until cleanup completes. Retrying never moves files to the trash a second time and preserves externally restored or replaced content.\n\n**Publishing your own skill:**\n\n- Find the publish action on the Skills page and point it at the skill's local folder. It zips the folder and uploads it — reading your directory in place, without copying or moving anything.\n- On first publish, you set the skill's **visibility**: PUBLIC (anyone in the org) or DEPARTMENT_SCOPED (only the departments you choose).\n- The local registry records what you published, so the app knows it's \"yours\" for future updates.\n\n**Updating an already-published skill:**\n\n- On your own skill's detail page you'll see a **发布新版本** (Publish New Version) button.\n- Edit the local folder however you want and publish — the version is **auto-incremented server-side**, you don't pick a number.\n- **Old versions stay live alongside the new one.** Users who already installed an older version keep it until they choose to update.\n- The display name and description are sent on every republish, so editing those metadata fields just means doing a republish.\n\n**Managing an already-published skill:**\n\n- Change who can see or use your skill from the management menu — public, shared with selected teams / departments, or private to you.\n- **Unpublish** makes it private again and returns ownership to your personal scope; it does not remove copies other users already installed.\n- **Authorship is fixed.** Only the original author's account can publish new versions of a given skill (enforced server-side as `NOT_AUTHOR`).\n\n**Browsing and installing others' skills:**\n\n- The marketplace lets you install skills into your global skills directory. You can request a specific version on install; the local registry tracks which version you have.\n\n**Notes:**\n\n- A skill folder without a `SKILL.md` at its root won't be picked up (lowercase `skill.md` is also accepted).\n- Project-scoped skills only show up in sessions whose working directory matches — useful for skills tied to a particular repo's conventions.\n- Editing files inside an installed skill folder takes effect on the next session start; you don't need to reinstall.\n- Uninstalling only removes your local copy. For your own published skills, use unpublish or manage visibility to change market availability.\n\nIn a new-task draft, the slash hover panel offers detail links for global skills. Project skill detail links are available after creating a task, when SkillHub can include that project in its scan.",
},
{
id: "updates-and-about",
diff --git a/apps/desktop/src/main/mcp-integrations/mcp-providers.ts b/apps/desktop/src/main/mcp-integrations/mcp-providers.ts
index 891899eccb..059a2f7cd3 100644
--- a/apps/desktop/src/main/mcp-integrations/mcp-providers.ts
+++ b/apps/desktop/src/main/mcp-integrations/mcp-providers.ts
@@ -375,6 +375,47 @@ export function createDesktopMcpProviders(deps: DesktopMcpProvidersDeps): LiziMc
createProject,
moveSession: createMoveSession(isSessionInTurn),
projectManagement: { list: listProjects, rename: renameProject, remove: removeProject },
+ skillLearning: async ({
+ callerSessionId,
+ input,
+ sourceKind,
+ hubSlug,
+ hubCatalogScope,
+ }) => {
+ try {
+ // Lazy import avoids coupling provider construction to learn-host startup.
+ // The callback is invoked only after bootstrap has initialized the host.
+ const { getLearnController } = await import('../learn-host/index.js');
+ const controller = getLearnController();
+ if (!controller) {
+ return {
+ ok: false,
+ errorCode: 'HOST_NOT_READY',
+ message: 'Cindy Learn is not ready yet.',
+ };
+ }
+ const { runId } = await controller.startLearn({
+ input,
+ sourceKind,
+ originSessionId: callerSessionId,
+ ...(hubSlug ? { hubSlug } : {}),
+ ...(hubCatalogScope ? { hubCatalogScope } : {}),
+ });
+ return { ok: true, runId };
+ } catch (err) {
+ const rawCode = (err as { code?: unknown })?.code;
+ const errorCode =
+ typeof rawCode === 'string'
+ && ['LEARN_BUSY', 'LEARN_INVALID_STATE', 'INVALID_PARAMS', 'NOT_FOUND'].includes(rawCode)
+ ? rawCode
+ : 'INTERNAL';
+ return {
+ ok: false,
+ errorCode,
+ message: err instanceof Error ? err.message : 'Failed to start Cindy Learn.',
+ };
+ }
+ },
resolveSurface: async ({ sessionId }) => {
const dbClient = tryGetDbClient();
if (!dbClient) return 'restricted';
diff --git a/apps/desktop/src/renderer/components/chat/SystemCard.tsx b/apps/desktop/src/renderer/components/chat/SystemCard.tsx
index 1b1bd7e742..e7cac09d7a 100644
--- a/apps/desktop/src/renderer/components/chat/SystemCard.tsx
+++ b/apps/desktop/src/renderer/components/chat/SystemCard.tsx
@@ -116,16 +116,17 @@ function HelpCard({ data }: { data?: Record<string, unknown> }) {
items: Array<{ name: string; description?: string; source: string }>,
) => (
<div className="flex flex-col gap-[2px]">
- {items.map((c) => (
- <div key={c.name} className={rowClass}>
- <span className={codeClass}>/{c.name}</span>
- <span className={descClass}>
- {builtInSkillDescriptionKey(c)
- ? t('skillhub.builtIn.skillCreator.description')
- : c.description ?? ''}
- </span>
- </div>
- ))}
+ {items.map((c) => {
+ const descriptionKey = builtInSkillDescriptionKey(c);
+ return (
+ <div key={c.name} className={rowClass}>
+ <span className={codeClass}>/{c.name}</span>
+ <span className={descClass}>
+ {descriptionKey ? t(descriptionKey) : c.description ?? ''}
+ </span>
+ </div>
+ );
+ })}
</div>
);
diff --git a/apps/desktop/src/renderer/components/new-chat/__tests__/SlashCommandPalette.test.tsx b/apps/desktop/src/renderer/components/new-chat/__tests__/SlashCommandPalette.test.tsx
index f6dac9e004..e2169f7d93 100644
--- a/apps/desktop/src/renderer/components/new-chat/__tests__/SlashCommandPalette.test.tsx
+++ b/apps/desktop/src/renderer/components/new-chat/__tests__/SlashCommandPalette.test.tsx
@@ -4,6 +4,7 @@ import { afterEach, beforeAll, describe, expect, it, vi } from 'vitest';
import zhCNCommon from '@/i18n/locales/zh-CN/common.json';
import type { UnifiedCommand } from '@/lib/slashCommands';
+import { CINDY_LEARN_SOURCE_DESCRIPTION } from '../../../../shared/cindyBuiltInSkills';
vi.mock('react-i18next', () => ({
useTranslation: () => ({ t: (key: string) => key }),
@@ -200,11 +201,17 @@ describe('SlashCommandPalette project Skill rows', () => {
expect(screen.queryByText('skillhub.builtIn.official')).toBeNull();
});
- it('marks Cindy Desktop /learn as official', () => {
+ it('localizes and marks the built-in Learn Skill as official', () => {
render(
<SlashCommandPalette
query=""
- commands={[{ kind: 'desktop', name: 'learn', description: 'Learn from this task' }]}
+ commands={[{
+ kind: 'agent-skill',
+ name: 'learn',
+ description: CINDY_LEARN_SOURCE_DESCRIPTION,
+ source: 'skill',
+ scope: 'user',
+ }]}
focusedIndex={0}
onFocusedIndexChange={vi.fn()}
onSelect={vi.fn()}
@@ -213,6 +220,7 @@ describe('SlashCommandPalette project Skill rows', () => {
);
expect(screen.getByText('skillhub.builtIn.official')).toBeTruthy();
+ expect(screen.getByText('skillhub.builtIn.learn.description')).toBeTruthy();
});
it('does not mark a user Skill named learn as official', () => {
diff --git a/apps/desktop/src/renderer/features/cc-agent/CCAgentSessionView.tsx b/apps/desktop/src/renderer/features/cc-agent/CCAgentSessionView.tsx
index aa8262df8d..fc165ba629 100644
--- a/apps/desktop/src/renderer/features/cc-agent/CCAgentSessionView.tsx
+++ b/apps/desktop/src/renderer/features/cc-agent/CCAgentSessionView.tsx
@@ -2478,23 +2478,6 @@ export function CCAgentSessionView({
}
return;
}
- if (payload.command === 'learn') {
- // /learn 的蒸馏在独立后台 session 跑(learn-host);这里只反馈启动结果。
- // 进度与"待审查"入口由 learn:event 状态流驱动(审查面板见 features/learn)。
- if (payload.error === 'learn-usage') {
- toast.warning(t('learn.toast.usage'));
- } else if (payload.error === 'learn-busy') {
- toast.warning(t('learn.toast.busy'));
- } else if (payload.error === 'learn-failed') {
- toast.error(t('learn.toast.failed'));
- } else if (payload.error === 'remote-unsupported') {
- toast.warning(t('commands.toast.remoteUnsupported'));
- } else if (payload.learnRunId) {
- // 状态卡只存 runId,状态本体由卡片内 useLearnRun 订阅 learn:event 实时刷新。
- insertSystemCard('learn', { runId: payload.learnRunId });
- }
- return;
- }
if (payload.command === 'workflows') {
// workflow 的主视图在右栏「后台任务」面板:有 live workflow 任务则打开面板
// 并定位其详情;没有(如重载后任务表已清空)也打开面板列表 —— 列表基于消息
@@ -4382,22 +4365,23 @@ export function CCAgentSessionView({
};
}, [historyLoaded, insertSystemCard, sessionId, learnRestoreKey]);
- // learn 卡跟随最新叙述:提案就绪 / 每轮修订刷新(awaiting-review 的
- // state-changed)时把本会话的 learn 卡移到消息流末尾 —— 卡片是 /learn 发出
- // 时插入的,蒸馏长输出把用户视线带到底部后,顶部的「查看提案」入口会被
- // 错过、误以为已装好(Chris 实测反馈)。移动只调位置不换消息对象。
+ // Learn 现在由 Agent Skill 通过宿主工具启动,不再有 Desktop command payload。
+ // 首个属于本会话的状态事件负责插入卡片;提案就绪 / 每轮修订刷新时再把卡片
+ // 移到消息流末尾,避免蒸馏长输出把「查看提案」入口留在顶部。
useEffect(() => {
if (!sessionId) return;
// subscribeLearnEvents:本机走 learn:event IPC;device-link 远程会话经
// onRemotePush 消费被控端转发的同名事件(learnTransport 内路由)。
const off = subscribeLearnEvents(sessionId, (payload) => {
if (payload.type !== 'state-changed') return;
- if (payload.run.status !== 'awaiting-review') return;
if (payload.run.sessionId !== sessionId && payload.run.originSessionId !== sessionId) return;
- makerChatStore.moveLearnCardToEnd(sessionId, payload.run.runId);
+ insertSystemCard('learn', { runId: payload.run.runId });
+ if (payload.run.status === 'awaiting-review') {
+ makerChatStore.moveLearnCardToEnd(sessionId, payload.run.runId);
+ }
});
return off;
- }, [sessionId]);
+ }, [insertSystemCard, sessionId]);
// session 切换时 reset consumed guard(切到别的 session 后再回来,理论上 pending
// 已被消费过、Map 也清掉了,但 ref 复用一份是为了 guard 可重入)。
diff --git a/apps/desktop/src/renderer/features/learn/learnTransport.ts b/apps/desktop/src/renderer/features/learn/learnTransport.ts
index 78da870c74..c5c69ce61f 100644
--- a/apps/desktop/src/renderer/features/learn/learnTransport.ts
+++ b/apps/desktop/src/renderer/features/learn/learnTransport.ts
@@ -27,7 +27,7 @@ import type { LearnEventPayload } from '../../../shared/learnTypes';
type FullLearn = typeof window.electronAPI.learn;
-/** 状态卡 / 审查面板消费的 learn 操作子集(start 不在此:/learn 统一走 desktop 命令路径)。 */
+/** 状态卡 / 审查面板消费的 learn 操作子集(start 由内置 Learn Skill 通过宿主工具触发)。 */
export interface RoutableLearn {
listRuns: FullLearn['listRuns'];
getProposalDiff: FullLearn['getProposalDiff'];
diff --git a/apps/desktop/src/renderer/features/skillhub/SkillhubHomeView.tsx b/apps/desktop/src/renderer/features/skillhub/SkillhubHomeView.tsx
index b373d694c9..6cb080c471 100644
--- a/apps/desktop/src/renderer/features/skillhub/SkillhubHomeView.tsx
+++ b/apps/desktop/src/renderer/features/skillhub/SkillhubHomeView.tsx
@@ -29,7 +29,10 @@ import {
PluginManagementPage,
} from '@/features/plugin/PluginManagementLayout';
import { buildLocalSkillRoute, findLocalSkillByPath } from './lib/localRoutes';
-import { builtInSkillDescriptionKey } from './lib/builtInSkillPresentation';
+import {
+ builtInSkillDescriptionKey,
+ isBuiltInLearnSkillEnabled,
+} from './lib/builtInSkillPresentation';
import { refresh as refreshSkillhub, useSkillhub } from './hooks/useSkillhub';
import {
MARKET_PAGE_SIZE,
@@ -476,6 +479,7 @@ export function SkillhubHomeView({
}
onClone={handleClone}
onManageAction={management.handleManageAction}
+ learnSkillEnabled={isBuiltInLearnSkillEnabled(skills, bootstrapped)}
/>
<MarketManagementDialogs controller={management} />
<InstallTargetPicker
diff --git a/apps/desktop/src/renderer/features/skillhub/SkillhubMarketListView.tsx b/apps/desktop/src/renderer/features/skillhub/SkillhubMarketListView.tsx
index 0749914b75..c008ed8bdf 100644
--- a/apps/desktop/src/renderer/features/skillhub/SkillhubMarketListView.tsx
+++ b/apps/desktop/src/renderer/features/skillhub/SkillhubMarketListView.tsx
@@ -18,7 +18,7 @@ import {
type SortBy,
type Visibility,
} from './hooks/useMarketList';
-import { refresh as refreshSkillhub } from './hooks/useSkillhub';
+import { refresh as refreshSkillhub, useSkillhub } from './hooks/useSkillhub';
import { MarketManagementDialogs, useMarketManagement } from './hooks/useMarketManagement';
import { getMarketSelected, setMarketSelected } from './hooks/useMarketSelection';
import { MarketCard } from './components/MarketCard';
@@ -31,6 +31,7 @@ import { syncMarketPreviewSelection } from './lib/marketPreviewSync';
import { useAuth } from '@/contexts/AuthContext';
import { CATEGORY_ALL } from '../../../shared/skillhubCategory';
import { useSkillhubIdentityPolicy } from './hooks/useSkillhubIdentityPolicy';
+import { isBuiltInLearnSkillEnabled } from './lib/builtInSkillPresentation';
const FILTER_CHIP_STYLE = { height: '32px', padding: '0 12px', fontSize: '12px' };
// Must match the global native scrollbar width in styles/globals.css.
@@ -77,6 +78,7 @@ export function SkillhubMarketListView() {
function SkillhubMarketListViewInner() {
const { t } = useTranslation();
const { user, isInitializing } = useAuth();
+ const { skills: localSkills, bootstrapped: skillhubBootstrapped } = useSkillhub();
const identityPolicy = useSkillhubIdentityPolicy(user);
const location = useLocation();
const navigate = useNavigate();
@@ -505,6 +507,7 @@ function SkillhubMarketListViewInner() {
: 'none'}
onClone={handleClone}
onManageAction={management.handleManageAction}
+ learnSkillEnabled={isBuiltInLearnSkillEnabled(localSkills, skillhubBootstrapped)}
/>
<MarketManagementDialogs controller={management} />
</div>
diff --git a/apps/desktop/src/renderer/features/skillhub/SkillhubMarketPreviewPanel.tsx b/apps/desktop/src/renderer/features/skillhub/SkillhubMarketPreviewPanel.tsx
index e96c1d057a..c6d01534ec 100644
--- a/apps/desktop/src/renderer/features/skillhub/SkillhubMarketPreviewPanel.tsx
+++ b/apps/desktop/src/renderer/features/skillhub/SkillhubMarketPreviewPanel.tsx
@@ -45,6 +45,7 @@ interface SkillhubMarketPreviewPanelProps {
primaryAction?: MarketCardPrimaryAction;
onClone?: (skill: MarketSkill) => void;
onManageAction?: (skill: MarketSkill, action: MarketCardManageAction) => void;
+ learnSkillEnabled?: boolean;
}
/**
@@ -62,6 +63,7 @@ export function SkillhubMarketPreviewPanel({
primaryAction = 'none',
onClone,
onManageAction,
+ learnSkillEnabled = true,
}: SkillhubMarketPreviewPanelProps) {
const { t } = useTranslation();
const navigate = useNavigate();
@@ -262,6 +264,8 @@ export function SkillhubMarketPreviewPanel({
{primaryAction === 'clone' ? (
<Button
variant="secondary"
+ disabled={!learnSkillEnabled}
+ title={learnSkillEnabled ? undefined : t('learn.hub.disabledHint')}
onClick={() => {
// Learn = 以该 skill 为参考蒸馏本地技能(不安装原件)。
// 不预创建会话:把 `/learn hub:<slug> ` 预填进系统原生的
diff --git a/apps/desktop/src/renderer/features/skillhub/components/__tests__/MarketLocalSkills.test.tsx b/apps/desktop/src/renderer/features/skillhub/components/__tests__/MarketLocalSkills.test.tsx
index 876297ab29..3dc5e241c9 100644
--- a/apps/desktop/src/renderer/features/skillhub/components/__tests__/MarketLocalSkills.test.tsx
+++ b/apps/desktop/src/renderer/features/skillhub/components/__tests__/MarketLocalSkills.test.tsx
@@ -85,6 +85,15 @@ describe('market Skill details', () => {
fireEvent.click(await screen.findByRole('menuitem', { name: 'skillhub.detail.uninstall' }));
await waitFor(() => expect(mocks.uninstall).toHaveBeenCalledWith(local.absolutePath, local.id));
});
+
+ it('disables Learn this skill when the built-in Learn Skill is disabled', async () => {
+ render(<MemoryRouter><SkillhubMarketPreviewPanel skill={market} open onClose={vi.fn()}
+ primaryAction="clone" onClone={vi.fn()} learnSkillEnabled={false} /></MemoryRouter>);
+
+ const learn = await screen.findByRole('button', { name: 'learn.hub.learnButton' });
+ expect((learn as HTMLButtonElement).disabled).toBe(true);
+ expect(learn.getAttribute('title')).toBe('learn.hub.disabledHint');
+ });
});
describe('market installed location matching', () => {
diff --git a/apps/desktop/src/renderer/features/skillhub/lib/__tests__/builtInSkillPresentation.test.ts b/apps/desktop/src/renderer/features/skillhub/lib/__tests__/builtInSkillPresentation.test.ts
new file mode 100644
index 0000000000..83364071b2
--- /dev/null
+++ b/apps/desktop/src/renderer/features/skillhub/lib/__tests__/builtInSkillPresentation.test.ts
@@ -0,0 +1,29 @@
+import { describe, expect, it } from 'vitest';
+
+import { CINDY_LEARN_SOURCE_DESCRIPTION } from '../../../../../shared/cindyBuiltInSkills';
+import { isBuiltInLearnSkillEnabled } from '../builtInSkillPresentation';
+
+describe('isBuiltInLearnSkillEnabled', () => {
+ it('waits for the local scan, then follows only the official Learn entry', () => {
+ expect(isBuiltInLearnSkillEnabled([], false)).toBe(true);
+ expect(isBuiltInLearnSkillEnabled([], true)).toBe(false);
+ expect(isBuiltInLearnSkillEnabled([{
+ name: 'learn',
+ description: 'My own Learn workflow',
+ scope: 'global',
+ cindyEnabled: true,
+ }], true)).toBe(false);
+ expect(isBuiltInLearnSkillEnabled([{
+ name: 'learn',
+ description: CINDY_LEARN_SOURCE_DESCRIPTION,
+ scope: 'global',
+ cindyEnabled: false,
+ }], true)).toBe(false);
+ expect(isBuiltInLearnSkillEnabled([{
+ name: 'learn',
+ description: CINDY_LEARN_SOURCE_DESCRIPTION,
+ scope: 'global',
+ cindyEnabled: true,
+ }], true)).toBe(true);
+ });
+});
diff --git a/apps/desktop/src/renderer/features/skillhub/lib/builtInSkillPresentation.ts b/apps/desktop/src/renderer/features/skillhub/lib/builtInSkillPresentation.ts
index 0a97b47d19..cb3f41c370 100644
--- a/apps/desktop/src/renderer/features/skillhub/lib/builtInSkillPresentation.ts
+++ b/apps/desktop/src/renderer/features/skillhub/lib/builtInSkillPresentation.ts
@@ -1,6 +1,11 @@
-import { isCindyBuiltInSkillMetadata } from '../../../../shared/cindyBuiltInSkills';
+import {
+ CINDY_LEARN_NAME,
+ CINDY_SKILL_CREATOR_NAME,
+ isCindyBuiltInSkillMetadata,
+} from '../../../../shared/cindyBuiltInSkills';
export const SKILL_CREATOR_DESCRIPTION_KEY = 'skillhub.builtIn.skillCreator.description' as const;
+export const LEARN_DESCRIPTION_KEY = 'skillhub.builtIn.learn.description' as const;
/**
* Built-in Skills keep their canonical metadata in English for agents. Cindy
@@ -13,6 +18,28 @@ export function builtInSkillDescriptionKey(
description?: string;
scope?: string;
},
-): typeof SKILL_CREATOR_DESCRIPTION_KEY | undefined {
- return isCindyBuiltInSkillMetadata(skill) ? SKILL_CREATOR_DESCRIPTION_KEY : undefined;
+): typeof SKILL_CREATOR_DESCRIPTION_KEY | typeof LEARN_DESCRIPTION_KEY | undefined {
+ if (!isCindyBuiltInSkillMetadata(skill)) return undefined;
+ if (skill.name === CINDY_SKILL_CREATOR_NAME) return SKILL_CREATOR_DESCRIPTION_KEY;
+ if (skill.name === CINDY_LEARN_NAME) return LEARN_DESCRIPTION_KEY;
+ return undefined;
+}
+
+/** Keep SkillHub's Learn shortcut aligned with the built-in Skill toggle. */
+export function isBuiltInLearnSkillEnabled(
+ skills: ReadonlyArray<{
+ builtIn?: boolean;
+ cindyEnabled?: boolean;
+ name: string;
+ description?: string;
+ scope?: string;
+ }>,
+ bootstrapped: boolean,
+): boolean {
+ return !bootstrapped || skills.some(
+ (skill) =>
+ skill.name === CINDY_LEARN_NAME
+ && isCindyBuiltInSkillMetadata(skill)
+ && skill.cindyEnabled !== false,
+ );
}
diff --git a/apps/desktop/src/renderer/i18n/locales/en/common.json b/apps/desktop/src/renderer/i18n/locales/en/common.json
index 42be79518a..b9a10bd67a 100644
--- a/apps/desktop/src/renderer/i18n/locales/en/common.json
+++ b/apps/desktop/src/renderer/i18n/locales/en/common.json
@@ -11139,6 +11139,9 @@
"officialDetail": "Included and maintained by Cindy.",
"skillCreator": {
"description": "Create or update a Cindy Skill with clear instructions and supporting resources."
+ },
+ "learn": {
+ "description": "Distill a reusable Skill from this task, a described workflow, or a SkillHub Skill through Cindy's review flow."
}
},
"common": {
@@ -12088,7 +12091,8 @@
"INTERNAL": "Internal error. Please try again later."
},
"hub": {
- "learnButton": "Learn this skill"
+ "learnButton": "Learn this skill",
+ "disabledHint": "Enable the built-in Learn Skill in Local Skills to use this action."
}
},
"planMode": {
diff --git a/apps/desktop/src/renderer/i18n/locales/ja/common.json b/apps/desktop/src/renderer/i18n/locales/ja/common.json
index e4a653b3e0..be4458e6cf 100644
--- a/apps/desktop/src/renderer/i18n/locales/ja/common.json
+++ b/apps/desktop/src/renderer/i18n/locales/ja/common.json
@@ -11123,6 +11123,9 @@
"officialDetail": "Cindy がアプリに同梱し、管理しています。",
"skillCreator": {
"description": "明確な手順と必要な補助リソースを備えた Cindy スキルを作成または更新します。"
+ },
+ "learn": {
+ "description": "現在のタスク、説明されたワークフロー、または SkillHub のスキルから再利用可能なスキルを抽出し、Cindy のレビューフローを経て保存します。"
}
},
"common": {
@@ -12071,7 +12074,8 @@
"INTERNAL": "内部エラーです。しばらくしてから再試行してください。"
},
"hub": {
- "learnButton": "このスキルを学習"
+ "learnButton": "このスキルを学習",
+ "disabledHint": "この操作を使うには、ローカルスキルで組み込みの Learn スキルを有効にしてください。"
}
},
"planMode": {
diff --git a/apps/desktop/src/renderer/i18n/locales/ko/common.json b/apps/desktop/src/renderer/i18n/locales/ko/common.json
index 0fdb7ac2c8..1485021849 100644
--- a/apps/desktop/src/renderer/i18n/locales/ko/common.json
+++ b/apps/desktop/src/renderer/i18n/locales/ko/common.json
@@ -11123,6 +11123,9 @@
"officialDetail": "Cindy가 앱에 포함하고 관리합니다.",
"skillCreator": {
"description": "명확한 지침과 필요한 지원 리소스를 갖춘 Cindy 스킬을 만들거나 업데이트합니다."
+ },
+ "learn": {
+ "description": "현재 작업, 설명한 워크플로 또는 SkillHub 스킬에서 재사용 가능한 스킬을 추출하고 Cindy 검토 절차를 거쳐 저장합니다."
}
},
"common": {
@@ -12071,7 +12074,8 @@
"INTERNAL": "내부 오류입니다. 잠시 후 다시 시도해 주세요."
},
"hub": {
- "learnButton": "이 스킬 학습하기"
+ "learnButton": "이 스킬 학습하기",
+ "disabledHint": "이 작업을 사용하려면 로컬 스킬에서 기본 제공 Learn 스킬을 활성화하세요."
}
},
"planMode": {
diff --git a/apps/desktop/src/renderer/i18n/locales/zh-CN/common.json b/apps/desktop/src/renderer/i18n/locales/zh-CN/common.json
index 7bf1975536..a95038bef3 100644
--- a/apps/desktop/src/renderer/i18n/locales/zh-CN/common.json
+++ b/apps/desktop/src/renderer/i18n/locales/zh-CN/common.json
@@ -11123,6 +11123,9 @@
"officialDetail": "由 Cindy 随应用提供并维护。",
"skillCreator": {
"description": "创建或更新 Cindy 技能,并编写清晰的说明和所需支持资源。"
+ },
+ "learn": {
+ "description": "从当前任务、描述的工作流或 SkillHub 技能中提炼可复用技能,并通过 Cindy 的审查流程保存。"
}
},
"common": {
@@ -12071,7 +12074,8 @@
"INTERNAL": "内部错误,请稍后重试"
},
"hub": {
- "learnButton": "学习此技能"
+ "learnButton": "学习此技能",
+ "disabledHint": "请先在本地技能中启用内置 Learn 技能。"
}
},
"planMode": {
diff --git a/apps/desktop/src/renderer/i18n/locales/zh-TW/common.json b/apps/desktop/src/renderer/i18n/locales/zh-TW/common.json
index 1ac8f29a28..fb852a8e5e 100644
--- a/apps/desktop/src/renderer/i18n/locales/zh-TW/common.json
+++ b/apps/desktop/src/renderer/i18n/locales/zh-TW/common.json
@@ -11123,6 +11123,9 @@
"officialDetail": "由 Cindy 隨應用程式提供並維護。",
"skillCreator": {
"description": "建立或更新 Cindy 技能,並編寫清楚的說明與所需支援資源。"
+ },
+ "learn": {
+ "description": "從目前任務、描述的工作流程或 SkillHub 技能中提煉可重用技能,並透過 Cindy 的審查流程儲存。"
}
},
"common": {
@@ -12071,7 +12074,8 @@
"INTERNAL": "內部錯誤,請稍後重試"
},
"hub": {
- "learnButton": "學習此技能"
+ "learnButton": "學習此技能",
+ "disabledHint": "請先在本機技能中啟用內建 Learn 技能。"
}
},
"planMode": {
diff --git a/apps/desktop/src/renderer/lib/__tests__/slashCommands.test.ts b/apps/desktop/src/renderer/lib/__tests__/slashCommands.test.ts
index ac80e837cd..33628866c3 100644
--- a/apps/desktop/src/renderer/lib/__tests__/slashCommands.test.ts
+++ b/apps/desktop/src/renderer/lib/__tests__/slashCommands.test.ts
@@ -1,4 +1,5 @@
import { describe, expect, it, vi } from 'vitest';
+import { CINDY_LEARN_SOURCE_DESCRIPTION } from '../../../shared/cindyBuiltInSkills';
import {
filterSlashCommands,
@@ -126,7 +127,12 @@ describe('filterSlashCommands', () => {
description: 'Create or update a Cindy Skill',
source: 'skill' as const,
},
- { kind: 'desktop' as const, name: 'learn', description: 'Learn' },
+ {
+ kind: 'agent-skill' as const,
+ name: 'learn',
+ description: CINDY_LEARN_SOURCE_DESCRIPTION,
+ source: 'skill' as const,
+ },
{ kind: 'agent-skill' as const, name: 'release-notes', source: 'skill' as const },
];
@@ -138,11 +144,23 @@ describe('filterSlashCommands', () => {
]);
});
- it('recognizes only the Desktop /learn command as official', () => {
+ it('recognizes the Cindy Learn Skill but not a same-name desktop command or user Skill', () => {
expect(isCindyOfficialSlashCommand({
kind: 'desktop',
name: 'learn',
description: 'Learn',
+ })).toBe(false);
+ expect(isCindyOfficialSlashCommand({
+ kind: 'agent-skill',
+ name: 'learn',
+ description: CINDY_LEARN_SOURCE_DESCRIPTION,
+ source: 'skill',
+ })).toBe(true);
+ expect(isCindyOfficialSlashCommand({
+ kind: 'agent-skill',
+ name: 'learn',
+ description: 'Distill a reusable Skill with Cindy',
+ source: 'skill',
})).toBe(true);
expect(isCindyOfficialSlashCommand({
kind: 'agent-skill',
diff --git a/apps/desktop/src/renderer/lib/slashCommands.ts b/apps/desktop/src/renderer/lib/slashCommands.ts
index 6544925568..e7288e2b88 100644
--- a/apps/desktop/src/renderer/lib/slashCommands.ts
+++ b/apps/desktop/src/renderer/lib/slashCommands.ts
@@ -19,10 +19,7 @@
import type { UnifiedCommand, AgentKind } from '@cindy/maker-core';
import { leadingSlashInvocation } from '@cindy/maker-shared';
import type { PiPackageCommandRuntimeStatus } from '@/../shared/piPackages';
-import {
- isCindyBuiltInSkillMetadata,
- isCindyOfficialDesktopCommandName,
-} from '@/../shared/cindyBuiltInSkills';
+import { isCindyBuiltInSkillMetadata } from '@/../shared/cindyBuiltInSkills';
export { leadingSlashInvocation };
@@ -45,9 +42,6 @@ export function isSlashCommandUnavailable(command: UnifiedCommand): boolean {
}
export function isCindyOfficialSlashCommand(command: UnifiedCommand): boolean {
- if (command.kind === 'desktop') {
- return isCindyOfficialDesktopCommandName(command.name);
- }
return command.kind === 'agent-skill' && isCindyBuiltInSkillMetadata(command);
}
@@ -207,9 +201,10 @@ export function isSlashCommandRosterReady(
}
// device-link 远程会话下 desktop 命令**全量可用**:业务语义在「会话归属设备」的命令
-// (/goal /learn /cmd)由控制端 main(commands/builtins.ts)按 ctx.deviceId 经隧道路由
-// 到被控端对应 channel(maker:goal:* / learn:* / desktop-cmd:run,均在 REMOTE_INVOKE_ALLOWLIST);
+// (/goal /cmd)由控制端 main(commands/builtins.ts)按 ctx.deviceId 经隧道路由
+// 到被控端对应 channel(maker:goal:* / desktop-cmd:run,均在 REMOTE_INVOKE_ALLOWLIST);
// 纯控制端 UI 命令(/help /clear /workflows /jump-session /issue)本就与会话归属无关。
+// /learn 是被控端 Agent 暴露的 Skill,通过同机 cindy_helper 启动 Learn host,不走此路径。
// 历史上这里有一张 DEVICE_LINK_UNAVAILABLE 黑名单(goal/learn,reviewer #354 / Codex #483
// 时代控制端还没有隧道路由)—— 隧道链路打通后已删除;被控端版本过旧不支持对应 channel 时,
// main 会广播 error: 'remote-unsupported',renderer toast 提示,不再静默剔除命令。
@@ -478,7 +473,7 @@ export interface DispatchContext {
workingDir?: string;
/** `/name args...` 中 name 后面的剩余文本; 没有则空串。 */
args?: string;
- /** device-link 远程会话的归属设备 id(本机会话缺省)。main 侧 /goal /learn /cmd
+ /** device-link 远程会话的归属设备 id(本机会话缺省)。main 侧 /goal /cmd
* 据此把业务体经隧道路由到被控端执行。 */
deviceId?: string;
}
diff --git a/apps/desktop/src/renderer/vite-env.d.ts b/apps/desktop/src/renderer/vite-env.d.ts
index e5953724c2..1bf84faa19 100644
--- a/apps/desktop/src/renderer/vite-env.d.ts
+++ b/apps/desktop/src/renderer/vite-env.d.ts
@@ -5545,13 +5545,10 @@ interface ElectronAPI {
timedOut: boolean;
spawnError?: string;
};
- /** /goal、/learn 共用:错误码(goal-usage / goal-no-session / goal-failed;
- * learn-usage / learn-busy / learn-failed)。 */
+ /** /goal 专用:错误码(goal-usage / goal-no-session / goal-failed)。 */
error?: string;
/** /goal 专用:动作('set'/'cleared'/'open-dialog'=打开新建目标弹窗)。 */
goalAction?: 'set' | 'cleared' | 'open-dialog';
- /** /learn 专用:启动成功时的 runId(关联 learn:event 状态流)。 */
- learnRunId?: string;
}) => void,
) => () => void;
diff --git a/apps/desktop/src/shared/cindyBuiltInSkills.ts b/apps/desktop/src/shared/cindyBuiltInSkills.ts
index d874a49d49..c0c1c07e32 100644
--- a/apps/desktop/src/shared/cindyBuiltInSkills.ts
+++ b/apps/desktop/src/shared/cindyBuiltInSkills.ts
@@ -1,6 +1,5 @@
export const CINDY_SKILL_CREATOR_NAME = 'cindy-skill-creator';
-
-const CINDY_OFFICIAL_DESKTOP_COMMAND_NAMES = new Set(['learn']);
+export const CINDY_LEARN_NAME = 'learn';
const CINDY_SKILL_CREATOR_SOURCE_DESCRIPTIONS = new Set([
'Create or update a Cindy Skill',
@@ -8,6 +7,19 @@ const CINDY_SKILL_CREATOR_SOURCE_DESCRIPTIONS = new Set([
'Create or update a Cindy Skill with appropriately scoped instructions and any needed supporting resources.',
]);
+export const CINDY_LEARN_SOURCE_DESCRIPTION =
+ "Distill a reusable Cindy Skill from the current task, a described workflow, or a SkillHub skill through Cindy's review flow when the user invokes /learn or explicitly asks to start Learn.";
+
+const CINDY_LEARN_SOURCE_DESCRIPTIONS = new Set([
+ CINDY_LEARN_SOURCE_DESCRIPTION,
+ 'Distill a reusable Skill with Cindy',
+]);
+
+const CINDY_BUILT_IN_SOURCE_DESCRIPTIONS = new Map<string, ReadonlySet<string>>([
+ [CINDY_SKILL_CREATOR_NAME, CINDY_SKILL_CREATOR_SOURCE_DESCRIPTIONS],
+ [CINDY_LEARN_NAME, CINDY_LEARN_SOURCE_DESCRIPTIONS],
+]);
+
/** Identify Cindy-owned metadata without treating another vendor's Skill Creator as official. */
export function isCindyBuiltInSkillMetadata(skill: {
builtIn?: boolean;
@@ -15,15 +27,11 @@ export function isCindyBuiltInSkillMetadata(skill: {
description?: string;
scope?: string;
}): boolean {
- if (skill.name !== CINDY_SKILL_CREATOR_NAME) return false;
+ const sourceDescriptions = CINDY_BUILT_IN_SOURCE_DESCRIPTIONS.get(skill.name);
+ if (!sourceDescriptions) return false;
if (skill.builtIn === true || skill.scope === 'system') return true;
return Boolean(
skill.description
- && CINDY_SKILL_CREATOR_SOURCE_DESCRIPTIONS.has(skill.description.trim()),
+ && sourceDescriptions.has(skill.description.trim()),
);
}
-
-/** Identify Desktop commands owned and shipped by Cindy. */
-export function isCindyOfficialDesktopCommandName(name: string): boolean {
- return CINDY_OFFICIAL_DESKTOP_COMMAND_NAMES.has(name);
-}
diff --git a/apps/desktop/src/shared/learnTypes.ts b/apps/desktop/src/shared/learnTypes.ts
index 24e130c33a..c34905df22 100644
--- a/apps/desktop/src/shared/learnTypes.ts
+++ b/apps/desktop/src/shared/learnTypes.ts
@@ -1,9 +1,9 @@
/**
* Learn 功能的跨进程共享类型 —— main / preload / renderer 单一来源。
*
- * Learn 是系统级能力:把任意来源(自由文本描述、hub skill、本地会话用法证据)
- * 蒸馏成一个本地 skill 提案,经 diff 审查确认后才落盘到 ~/.agents/skills/。
- * 引擎实现在 apps/desktop/src/main/learn-host/。
+ * Learn 是由内置 Skill 触发、由系统托管的能力:把任意来源(自由文本描述、hub
+ * skill、本地会话用法证据)蒸馏成一个本地 skill 提案,经 diff 审查确认后才落盘
+ * 到 ~/.agents/skills/。状态机实现在 apps/desktop/src/main/learn-host/。
*/
import type { ToolLoopErrorDetails } from '@cindy/maker-shared/tool-loop-error';
diff --git a/packages/lizi-mcps/src/__tests__/startSkillLearning.test.ts b/packages/lizi-mcps/src/__tests__/startSkillLearning.test.ts
new file mode 100644
index 0000000000..0d24fcd1b0
--- /dev/null
+++ b/packages/lizi-mcps/src/__tests__/startSkillLearning.test.ts
@@ -0,0 +1,103 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { XdtHelperToolRegistry } from '../lizi_xdtHelperToolRegistry.js';
+import { registerStartSkillLearningTool } from '../xdt-helper/start_skill_learning.js';
+
+function payload(result: { content: Array<{ type: string; text?: string }> }): Record<string, unknown> {
+ const text = result.content.find((block) => block.type === 'text')?.text;
+ if (!text) throw new Error('missing text payload');
+ return JSON.parse(text) as Record<string, unknown>;
+}
+
+describe('start_skill_learning', () => {
+ it('binds the current task and starts a session Learn run', async () => {
+ const registry = new XdtHelperToolRegistry();
+ const startSkillLearning = vi.fn(async () => ({ ok: true as const, runId: 'run-1' }));
+ registerStartSkillLearningTool(registry, {
+ getSessionContext: () => ({
+ agentKind: 'codex',
+ workingDir: '/repo',
+ sessionId: 'session-1',
+ }),
+ startSkillLearning,
+ });
+
+ const result = await registry.call('start_skill_learning', {
+ source_kind: 'session',
+ input: '',
+ });
+
+ expect(startSkillLearning).toHaveBeenCalledWith({
+ callerSessionId: 'session-1',
+ input: '',
+ sourceKind: 'session',
+ });
+ expect(payload(result)).toMatchObject({ ok: true, run_id: 'run-1', status: 'collecting' });
+ });
+
+ it('normalizes SkillHub input and defaults its catalog scope', async () => {
+ const registry = new XdtHelperToolRegistry();
+ const startSkillLearning = vi.fn(async () => ({ ok: true as const, runId: 'run-2' }));
+ registerStartSkillLearningTool(registry, {
+ getSessionContext: () => ({
+ agentKind: 'claude-code',
+ workingDir: '/repo',
+ sessionId: 'session-2',
+ }),
+ startSkillLearning,
+ });
+
+ await registry.call('start_skill_learning', {
+ source_kind: 'hub',
+ hub_slug: 'release-notes',
+ input: ' keep the checks ',
+ });
+
+ expect(startSkillLearning).toHaveBeenCalledWith({
+ callerSessionId: 'session-2',
+ input: 'keep the checks',
+ sourceKind: 'hub',
+ hubSlug: 'release-notes',
+ hubCatalogScope: 'market',
+ });
+ });
+
+ it.each([
+ [{ source_kind: 'freetext', input: ' ' }, 'INVALID_ARGS'],
+ [{ source_kind: 'hub', input: '' }, 'INVALID_ARGS'],
+ [{ source_kind: 'session', input: '', hub_slug: 'extra' }, 'INVALID_ARGS'],
+ ])('rejects inconsistent arguments %#', async (args, expectedErrorCode) => {
+ const registry = new XdtHelperToolRegistry();
+ const startSkillLearning = vi.fn();
+ registerStartSkillLearningTool(registry, {
+ getSessionContext: () => ({
+ agentKind: 'pi',
+ workingDir: '/repo',
+ sessionId: 'session-3',
+ }),
+ startSkillLearning,
+ });
+
+ const result = await registry.call('start_skill_learning', args);
+
+ expect(payload(result)).toMatchObject({ ok: false, errorCode: expectedErrorCode });
+ expect(startSkillLearning).not.toHaveBeenCalled();
+ });
+
+ it('fails closed without a bound Cindy task', async () => {
+ const registry = new XdtHelperToolRegistry();
+ const startSkillLearning = vi.fn();
+ registerStartSkillLearningTool(registry, {
+ getSessionContext: () => ({ agentKind: 'codex', workingDir: '/repo' }),
+ startSkillLearning,
+ });
+
+ const result = await registry.call('start_skill_learning', {
+ source_kind: 'session',
+ input: '',
+ });
+
+ expect(payload(result)).toMatchObject({ ok: false, errorCode: 'NO_SESSION_CONTEXT' });
+ expect(startSkillLearning).not.toHaveBeenCalled();
+ });
+});
diff --git a/packages/lizi-mcps/src/lizi_xdtHelperMcpServer.ts b/packages/lizi-mcps/src/lizi_xdtHelperMcpServer.ts
index 8311c07284..78ab63194b 100644
--- a/packages/lizi-mcps/src/lizi_xdtHelperMcpServer.ts
+++ b/packages/lizi-mcps/src/lizi_xdtHelperMcpServer.ts
@@ -5,7 +5,7 @@
*
* 设计:
* - server name = `cindy_helper`,essential(常开,不可被用户关闭)
- * - 所有工具走 `list_tools` / `call_tool` 两个入口,渐进式发现,分五类:
+ * - 所有工具走 `list_tools` / `call_tool` 两个入口,渐进式发现:
* - 'cindy' : 只读自省 (get_capabilities / get_current_session_id)
* - 'history' : 只读查询本地数据库聊天历史与输入队列 (list_workdirs /
* list_sessions / list_session_queue / get_chat_history /
@@ -14,6 +14,7 @@
* archive_sessions / unarchive_sessions)
* - 'feedback': 官方反馈提交 (submit_github_issue)
* - 'handoff' : session 间 handoff 原语 (send_to_session),供 skill 跨会话路由
+ * - 'skills' : Cindy 宿主管理的 Skill 工作流
* - send_to_session 曾经直接顶层注册;现归入 handoff 类目走 call_tool,与改名工具
* 隔离(不同 category),避免 LLM 在"改 session 名"意图下误选它(见 issue #287)。
* - 协同 team 工具(start_team / create_worker / …)已拆到独立的 `cindy_orca` server
@@ -56,12 +57,14 @@ import {
registerGetChatHistoryTool,
registerSearchChatHistoryTool,
registerSubmitGithubIssueTool,
+ registerStartSkillLearningTool,
} from './xdt-helper/index.js';
import type { SubmitGithubIssueDeps } from './xdt-helper/submit_github_issue.js';
import type { SetCurrentSessionTitleDeps } from './xdt-helper/set_current_session_title.js';
import type { RenameSessionsDeps } from './xdt-helper/rename_sessions.js';
import type { ArchiveSessionsDeps } from './xdt-helper/archive_sessions.js';
import type { SendToSessionCallback } from './xdt-helper/send_to_session.js';
+import type { StartSkillLearningCallback } from './xdt-helper/start_skill_learning.js';
import {
registerBotSkillTools,
type BotSkillCallbacks,
@@ -111,7 +114,7 @@ const CALL_TOOL_INPUT = {
// list_tools 入口类目: cindy(自省) / control(会话控制面) / history(聊天历史) / feedback(官方反馈提交) / handoff(session 间 handoff)。
// 协同 team 工具已拆到独立 cindy_orca server(插件开关 gate)。
-const CATEGORY_ENUM = ['cindy', 'control', 'history', 'feedback', 'handoff', 'bots'] as const;
+const CATEGORY_ENUM = ['cindy', 'control', 'history', 'feedback', 'handoff', 'skills', 'bots'] as const;
interface SessionTaskCallbacks {
startSessionTask(params: {
@@ -634,6 +637,8 @@ export interface XdtHelperMcpDeps {
* 路由的原语, 放在 essential 的 cindy_helper 下常开保证 skill 永不断。
*/
sendToSession?: SendToSessionCallback;
+ /** Cindy-managed Learn flow; registered in the skills category when supplied by the host. */
+ skillLearning?: StartSkillLearningCallback;
/** Register an existing local directory as a Cindy project without starting a task. */
createProject?: CreateProjectCallback;
moveSession?: MoveSessionCallback;
@@ -801,6 +806,12 @@ export function createXdtHelperMcpServer(
sendToSession: deps.sendToSession,
});
}
+ if (deps.skillLearning) {
+ registerStartSkillLearningTool(registry, {
+ getSessionContext: () => resolveLiziMcpSessionContext(sessionCtx),
+ startSkillLearning: deps.skillLearning,
+ });
+ }
// 伙伴消息与 Session 任务控制统一进入 bots 类目,由调用时的任务身份限制发现与执行。
if (deps.botSkills) {
registerBotSkillTools(registry, {
diff --git a/packages/lizi-mcps/src/lizi_xdtHelperToolRegistry.ts b/packages/lizi-mcps/src/lizi_xdtHelperToolRegistry.ts
index 113fb597ff..a0ff58f6d5 100644
--- a/packages/lizi-mcps/src/lizi_xdtHelperToolRegistry.ts
+++ b/packages/lizi-mcps/src/lizi_xdtHelperToolRegistry.ts
@@ -35,6 +35,9 @@ import { z } from 'zod';
* session,或为业务对象新建专属 session),供 skill 路由用。单独成类(不并入 control)
* 是为了让 list_tools(control) 的"改会话标题"结果里不混入 handoff,避免 LLM 在"改名"
* 意图下误选 send_to_session。
+ *
+ * 'skills' 是由 Cindy 宿主管理的 Skill 工作流入口。工具只负责启动,
+ * staging、审查与安装仍由宿主状态机控制。
*/
export type XdtHelperToolCategory =
| 'cindy'
@@ -42,6 +45,7 @@ export type XdtHelperToolCategory =
| 'control'
| 'feedback'
| 'handoff'
+ | 'skills'
| 'bots';
export type XdtHelperToolContentBlock =
diff --git a/packages/lizi-mcps/src/xdt-helper/index.ts b/packages/lizi-mcps/src/xdt-helper/index.ts
index e10d578b70..d00cbb5a40 100644
--- a/packages/lizi-mcps/src/xdt-helper/index.ts
+++ b/packages/lizi-mcps/src/xdt-helper/index.ts
@@ -156,6 +156,10 @@ export {
type SubmitGithubIssueHostErr,
type SubmitGithubIssueHostErrorCode,
} from './submit_github_issue.js';
+export {
+ registerStartSkillLearningTool,
+ type StartSkillLearningCallback,
+} from './start_skill_learning.js';
export type {
XdtHelperHistoryDeps,
HistoryAgentKind,
diff --git a/packages/lizi-mcps/src/xdt-helper/start_skill_learning.ts b/packages/lizi-mcps/src/xdt-helper/start_skill_learning.ts
new file mode 100644
index 0000000000..c5247408ae
--- /dev/null
+++ b/packages/lizi-mcps/src/xdt-helper/start_skill_learning.ts
@@ -0,0 +1,72 @@
+import { z } from 'zod';
+
+import type { XdtHelperToolRegistry } from '../lizi_xdtHelperToolRegistry.js';
+import type { ControlResult, LiziMcpSessionContext } from '../types.js';
+import { errorPayload, okPayload } from './_payload.js';
+
+export type StartSkillLearningCallback = (params: {
+ callerSessionId: string;
+ input: string;
+ sourceKind: 'session' | 'freetext' | 'hub';
+ hubSlug?: string;
+ hubCatalogScope?: 'market' | 'team';
+}) => Promise<ControlResult<{ runId: string }, string>>;
+
+export function registerStartSkillLearningTool(
+ registry: XdtHelperToolRegistry,
+ deps: {
+ getSessionContext: () => LiziMcpSessionContext;
+ startSkillLearning: StartSkillLearningCallback;
+ },
+): void {
+ registry.register({
+ name: 'start_skill_learning',
+ category: 'skills',
+ description:
+ "Start Cindy's managed Learn flow for the current task. The host gathers evidence, distills into a separate task, stages the proposed Skill, and requires review before installation. Use only for an explicit /learn request. Call once and do not poll.",
+ inputShape: {
+ source_kind: z.enum(['session', 'freetext', 'hub']),
+ input: z.string().max(12_000).optional(),
+ hub_slug: z.string().regex(/^[a-z0-9][a-z0-9-]*$/).max(200).optional(),
+ hub_catalog_scope: z.enum(['market', 'team']).optional(),
+ },
+ handler: async ({ source_kind, input, hub_slug, hub_catalog_scope }) => {
+ const context = deps.getSessionContext();
+ if (!context.sessionId) {
+ return errorPayload('NO_SESSION_CONTEXT', 'No Cindy task is bound to this call.');
+ }
+
+ const normalizedInput = input?.trim() ?? '';
+ if (source_kind === 'freetext' && !normalizedInput) {
+ return errorPayload('INVALID_ARGS', 'A freetext Learn request requires non-empty input.');
+ }
+ if (source_kind === 'hub' && !hub_slug) {
+ return errorPayload('INVALID_ARGS', 'A SkillHub Learn request requires hub_slug.');
+ }
+ if (source_kind !== 'hub' && (hub_slug || hub_catalog_scope)) {
+ return errorPayload(
+ 'INVALID_ARGS',
+ 'hub_slug and hub_catalog_scope are only valid when source_kind is hub.',
+ );
+ }
+
+ const result = await deps.startSkillLearning({
+ callerSessionId: context.sessionId,
+ input: normalizedInput,
+ sourceKind: source_kind,
+ ...(hub_slug ? { hubSlug: hub_slug } : {}),
+ ...(source_kind === 'hub'
+ ? { hubCatalogScope: hub_catalog_scope ?? 'market' }
+ : {}),
+ });
+ return result.ok
+ ? okPayload({
+ run_id: result.runId,
+ status: 'collecting',
+ guidance:
+ 'Learn started. Progress and the review action appear in Cindy; do not call this tool again or poll.',
+ })
+ : errorPayload(result.errorCode, result.message);
+ },
+ });
+}