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。

chore(plugin): 同步主干并迁移目标接口手册

liugaoweiae9d33a556ac
diff --cc apps/desktop/resources/system-skills/cindy-plugin-creator/references/plugin-agent-tasks.md
index 0000000000,48fe09560e..b2840c9d6d
mode 000000,100644..100644
--- a/apps/desktop/resources/system-skills/cindy-plugin-creator/references/plugin-agent-tasks.md
+++ b/apps/desktop/resources/system-skills/cindy-plugin-creator/references/plugin-agent-tasks.md
@@@ -1,0 -1,297 +1,307 @@@
+ ## 4.11 发起 Agent 新回合(agent 能力)
+
+ 这个能力让你的 `main.js` 把一段文字作为**普通用户消息**交给 Cindy Agent,适合
+ “用户在插件卡片上点继续,然后 Agent 接着做”的流程。它不是系统提示词,也不会
+ 修改该会话里其它插件或 Agent 的长期规则。
+
+ 最安全、也是默认的用法,是消费 `card-action` 事件里的真实用户点击票:
+
+ ```js
+ cindy.onHostMessage(async function (msg) {
+ if (msg.type !== 'event' || msg.name !== 'card-action') return;
+
+ const result = await cindy.agent.run({
+ mode: 'continue', // continue = 继续原会话;fork = 从最新回复分叉;new = 新建会话
+ promptTemplate: '用户要求:{{user_message}}\n插件事件:{{event_json}}\n请继续处理。',
+ userMessage: msg.prompt || '继续',
+ event: { actionId: msg.actionId, callId: msg.callId },
+ userActionToken: msg.userActionToken,
+ // title: '插件创建的新任务' // 仅 mode:'new' 时使用
+ });
+
+ if (!result.ok) {
+ // result.errorCode / result.message 可用于把失败原因画回卡片
+ return;
+ }
+ // result.sessionId = 实际工作的会话;disposition 说明新建/恢复/排队/分叉
+ });
+ ```
+
+ 模板规则由主机强制:
+
+ - `promptTemplate` 必须且只能出现一次 `{{user_message}}`;主机把
+ `userMessage` 填进去。`{{event_json}}` 可出现零次或多次,主机统一替换成
+ `event` 的 JSON。不要自己用字符串拼接绕开模板;
+ - `mode:'continue'` 使用被点卡片所属的原会话;`fork` 从原会话最新一条有效
+ Agent 回复处分叉后再发送;`new` 继承原会话的 Agent、模型和工作目录配置;
+ - 票据绑定当前插件与卡片所属会话,两分钟有效、只能成功提交一次。runner 失败也
+ 不退票,避免一次点击被放大成多次收费回合;拿不到 `userActionToken` 时不要调用;
+ - 会话正在工作时不会硬插队,主机会把请求放进该会话的输入队列。最终文字、插件 id、
+ 插件版本、模板和事件 JSON 会随用户消息一起留存,方便用户知道这轮从哪里来。
+
+ 只有清单额外声明 `"agent": { "background": true }` 时,才可不用当次票据:
+
+ ```js
+ await cindy.agent.run({
+ mode: 'continue',
+ trigger: 'background',
+ sessionId: rememberedSessionId,
+ promptTemplate: '后台任务有新结果:{{user_message}}\n{{event_json}}',
+ userMessage: '请检查并继续',
+ event: { jobId: 'job-123', state: 'done' }
+ });
+ ```
+
+ 后台调用只能使用用户过去点击过你卡片、已与你建立关联的会话;每个插件同时只处理
+ 一条 Agent 请求,后台请求之间至少间隔 10 秒。这个能力可能自动产生模型费用,只在
+ 产品确实需要时申请,不要把 `sessionId` 当作任意跨会话控制口。
+
+ ### 4.11.1 旧版任务接口:让 Agent 替你干活并取回结果(errand)
+
+ `agent.run` 用于用户已关联任务的交互;旧版 `errand` 接口提供结果查询适配:
+ 任务在宿主按 sessionKey 关联的普通任务里运行,Agent 的最终回复文字交回**你**手里继续用。
+ 需声明 `"agent": { "errand": true }`(插件详情高风险单列)。
+
+ ```js
+ // 提交(默认异步:先拿单号,再轮询取件——Agent 干活是分钟级的):
+ const r = await cindy.agent.errand({
+ task: '阅读工作目录下的 README 并总结要点(200 字以内)',
+ // context: { anything: '结构化上下文,主机 JSON 化后附在任务消息尾部' },
+ // title: '我的插件任务', // 仅首次创建对应 errand 会话时用作标题
+ // workingDir: repoDir, // 可选:请求建在某目录(只认用户亲选过的,见下)
+ // sessionKey: 'pr-123', // 可选:分会话钥匙(1–64 位字母/数字/._-)。
+ // // 不传 = 插件共用一间;同钥匙同间、异钥匙各间,
+ // // 适合按业务对象各聊各的(如每条 PR 一间,标题
+ // // 在该间首次创建时用 title 定,正好带上对象编号)
+ // mode: 'wait', // 同步等到完成(30 分钟顶);默认不传 = 异步
+ // userActionToken: msg.userActionToken, // 卡片点击票;校验后切到 errand 任务,一次性
+ callId: msg.callId,
+ });
+ // 受理:{ ok:true, jobId, status:'running', sessionId }
+ // 轮询取件(建议间隔 ≥5s;做成"提交 + 查询"两个工具让 AI 自己掌握节奏):
+ const q = await cindy.agent.queryErrand({ jobId: r.jobId });
+ // 进行中:{ ok:true, jobId, status:'running', sessionId, elapsedSeconds }
+ // 完成: { ok:true, jobId, status:'done', sessionId, text, agentKind, model }
+ // 失败: { ok:false, errorCode, message }
+ ```
+
+ 主机强制的边界(都不是建议):
+
+ - **任务只进普通 user 消息**,绝不进 system prompt;
+ - errand 会话在**侧边栏可见**,用户可随时旁观、叫停——errand 不支持隐藏;普通任务的
+ 后台隐藏只能经 §4.11.3 的 `hiddenTasks` 声明,且用户始终能在插件详情页查看与接手;
+ - 这是旧版任务接口,不是插件全部 AI 能力。普通任务管理用 §4.11.3,继续用户任务用 §4.11,
+ 快问快答用 §4.0.2;不要把这些能力统一称为代办。
+ - 新建任务共用插件详情「任务设置」中的模型组合(Agent、供应商、模型、推理强度、Fast)。
+ 没有覆盖时,沿用宿主核实的同插件本机在途 `callId` 所属任务;面板直接创建使用当前新任务选择。
+ 无显式覆盖的已有专属任务保留自身模型,用户在任务中改选后可继续复用。
+ 显式配置发生冲突时,新任务创建成功才替换映射,旧任务与历史保留。
+ - 保存、创建与派发前校验真实的模型/Agent/供应商组合;失效时引导用户到任务设置改选,
+ 或修复供应商连接。不静默换模型、不从报错猜凭证失效,也不把目录可用当作远端推理一定成功。
+ - 权限独立来自用户插件设置;旧接口缺省保留历史 plan 值及原 Agent 行为,不将它宣称为
+ 跨 Agent 的只读保证。新插件应使用普通任务接口,其缺省为普通任务的 ask 权限。
+ 用户可显式选择 ask / acceptEdits / auto;不继承调用任务的完全访问。工作目录由宿主分配。
+ - 目录有一个受控例外:run 请求可带 `workingDir`(绝对路径)**转述**一个目录,
+ 让 errand 会话建在项目里(Agent 能看到代码)。这不是授权——主机只认用户
+ 此前用 pick 能力(§4.14)在系统选目录窗口里**亲手选过**的目录(主机自己记的
+ 台账),别的路径一律 `INVALID_REQUEST`,此时应引导用户去你的设置页重新
+ 选一次目录;用户在「任务设置」卡里配置了目录时,以用户配置优先、本字段忽略;
+ - 每插件同时 1 单在途、相邻提交至少隔 10 秒;结果超过 64K 字符会截断(尾部带
+ 标记);完成结果保留 30 分钟,应用重启后查无此单(按可重新提交处理);
+ `sessionKey` 只是分间,**不放大并发**——不同钥匙的两单同样要排队;
+ - 可选 `userActionToken`:把 `card-action` 里主机签发的点击票原样带上。
+ 主机校验通过才把这次派活当成用户发起并切到 errand 任务;票一次性消费,
+ 不能再拿去 `agent.run` 或再派一次。面板上的真实点击由主机自己记账,
+ 必须紧挨着这次派活,不能靠几分钟前点过输入框来顶替;
+ - `errorCode:'BUSY'` = 你已有一单在途,或用户恰好正在 errand 会话里说话;
+ `'NO_CANDIDATE'` 不存在于此——但会话创建/派发失败有 `'SESSION_UNAVAILABLE'`,
+ 超时有 `'TIMEOUT'`(任务可能仍在会话里继续,提示用户打开会话查看)。
+ - 这个能力必然产生模型费用且耗时分钟级:能用快问快答(§4.0.2)解决的,不要派活。
+
+ ### 4.11.2 请用户新建一条自动化(agent.schedule 加档)
+
+ **这是"让插件里的内容自己保持新鲜"的正路。** 你的插件自己跑不了业务逻辑——沙箱只在
+ 被唤起时活着,也没有定时器。要做出「每小时帮我看一眼,有事就点亮插件入口」这种效果,
+ 正确的分工是:
+
+ 插件不是执行者,而是**定时任务的目标**。执行者是 Cindy 的 AI。
+
+ 完整回路(以「Codex 重置提醒」为例):
+
+ 1. 用户在你的面板上点一个选项,比如「重置时间快到了提醒我」;
+ 2. 你调 `cindy.agent.requestSchedule(...)`,请主机**打开预填好的新建自动化面板**;
+ 3. 用户在面板上选个模型(或就用默认)→ **亲手点保存**。任务这才存在;
+ 4. 到点了,Cindy 起一轮 AI 去干活:查本机重置时间、看 X 上的相关发帖、**判断**要不要
+ 提醒——这些判断是 AI 做的,不是你做的;
+ 5. 那一轮 AI **调用你申报的 tool**(§3)把结果交给你,你在 tool 里更新自己的数据;
+ 6. 你顺手发一个未读角标(§4.9.1),用户的插件入口和图标上就亮起点;
+ 7. 用户回来点开面板,看到刷新后的内容。
+
+ 所以你需要的是三样东西的组合:`agent.schedule` 加档(第 2 步)+ 一个 `tool`(第 5 步)
+ + `badge` 能力(第 6 步)。三者缺一,回路就断在那里。
+
+ 需声明至少一个 `tools` 条目、`"agent": { "schedule": true }`、`"badge": true`
+ 以及 badge 所需的 `panel`(插件详情里单列一档,文案会告诉用户
+ "任务由你亲手保存、跑起来会产生模型费用")。
+
+ ```js
+ // 用户在面板上点了「提醒我」之后:
+ const r = await cindy.agent.requestSchedule({
+ name: 'Codex 重置提醒', // 预填的自动化名称(≤60 字)
+ prompt: [ // 到点了让 AI 干什么——用自然语言写清楚,
+ '检查本机 Codex 的限额重置时间。', // 包含"什么情况下才值得提醒我"
+ '再看一眼 X 上 @tobi 最近有没有相关发帖。',
+ '如果重置时间在 2 小时内,调用 codex-reset-planner 插件的 update_status 工具',
+ '把最新状态写回去;否则什么都不用做。',
+ ].join('\n'), // (≤2000 字)
+ intervalMs: 60 * 60 * 1000, // 可选:建议每小时一次。**最小 30 分钟**,
+ // 低于此值主机会自动上调
+ });
+ // { ok: true } = 请求已被接受并投递(**不保证面板真开了,更不代表用户存了**)
+ // { ok:false, errorCode:'PERMISSION_DENIED' | 'INVALID_REQUEST'
+ // | 'RATE_LIMITED' | 'HOST_NOT_READY' | 'INTERNAL', message }
+ ```
+
+ 主机强制的边界(都不是建议):
+
+ - **你只能打开面板,不能创建任务。** 没有任何"直接建一条自动化"的接口——主机这一侧
+ 压根没接调度存储,不是"忍着不用"。用户不点保存,什么都不会发生;
+ - **本版没有回执。** `ok:true` 只表示请求被接受并投递给了主壳窗口:用户当时可能正开着
+ 另一个自动化表单在编辑,那种情况下本次草稿会被**丢弃**(保护他没保存的输入),他看到
+ 一句提示、面板不换内容。即使面板正常打开,任务也要他亲手点保存才落库。所以你的 UI
+ **不要**显示"已开启"这类完成态,写"已为你打开创建面板,请确认"才准确;
+ 想确认用户是否照做了,当前唯一可信的信号是任务真的跑起来调了你的 tool。
+ **后续版本会补上**:任务与发起插件的**绑定关系**,以及你查询 / 管理**自己绑定的那条
+ 任务**(是否有效、下次运行时间、频率,以及改时间 / 暂停 / 关掉)。届时你就能在自己面板
+ 上显示"已开启 · 每小时 · 下次 15:00"并让用户就地改。绑定本身即授权边界:你只能看和改
+ 自己请求创建的那条,看不到用户的其它自动化;
+ - `prompt` 里要**自己说清楚该调你哪个工具**(见上面示例第 3 行)。AI 不会自动猜到
+ "跑完要更新哪个插件";
+ - 预填内容会**净化 + 截断**(去控制字符,名称 60 字 / prompt 2000 字);净化后为空一律
+ `INVALID_REQUEST`;
+ - `intervalMs` 低于 **30 分钟**会被自动上调。这不是权限闸门(用户自己在面板上改成
+ 1 分钟是他的自由),是不让你预填出一个每分钟烧一次模型额度的任务;
+ - 同一插件两次请求至少隔 **15 秒**(`RATE_LIMITED`)。这个面板是打断式的——它会把
+ 用户从当前页带到自动化页,别拿它刷屏;
+ - 面板上会显示**是你在请求**(插件名由主机填,你伪装不了),用户永远知道在替谁保存;
+ - **面板会开在主窗口**,不是你的面板窗。用户把你的面板拉成独立窗口后点这个入口时,
+ 创建表单出现在主窗口里(独立面板窗挂的是轻壳,承载不了自动化页)——文案上别写
+ "将在此处打开",写"去自动化页确认"之类更准;
+ - 一个都没有主窗口时(极端情况)→ `HOST_NOT_READY`。
+
+ 什么时候**不该**用它:一次性的事,用快问快答(§4.0.2)或普通任务接口
+ (§4.11.3)。这个加档是给"长期定期刷新"用的,每条任务都会反复产生模型费用。
+
+ ### 4.11.3 新建任务与继续任务(普通 Session)
+
+ 先按业务选择:
+ - 当前 Agent 已在处理你的工具:返回数据让它继续,不新建任务。
+ - 用户在稿件面板提交修改:`cindy.agent.run({mode: 'continue', ...})` 继续已关联原任务。OpenDesign 当前采用这一方式。
+ - 独立完成一项工作:`cindy.tasks.create` 新建普通任务,再用 `send` 开始执行。保存 taskId 后可继续同一任务。
+ - 需要更新插件页面:查询 `getRun/listRuns` 与 `readMessages`;没有默认回叫,不自动唤醒伙伴或 Agent。
+
+ 用户界面统一叫「新建任务」「打开任务」「继续任务」。任务能使用什么模型、工具和权限,由普通任务配置与用户授权决定。
+ 插件身份/业务关联在调用方保存,不把普通任务做成另一种产品对象。伙伴的完成回叫只属于伙伴自己的流程。
+
+ 声明 `"agent": { "tasks": true }` 后,逻辑页可使用 `cindy.tasks`。它是独立权限,
+ 旧 `errand` 声明不自动取得该权限。任务默认可见:出现在任务列表,用户可查看和接手。
+ 安装时已明确展示并确认的任务能力不重复询问;否则首次使用时通过现有宿主权限界面确认并记录独立批准。旧版保存的未知字段不会自动授权。
+ 用户拒绝或确认界面不可用时返回 `PERMISSION_DENIED`,不影响插件其它功能;不得自动循环重试确认。
+ 面板通过既有逻辑页通道调用,不获得新的 preload 或内部 IPC 权限。
+
-先调用 `capabilities()` 获取实际支持操作。当前仅支持本插件创建的本机普通任务:
++插件需要向项目、已有任务或伙伴投递内容时,使用独立的 `cindy.targets`(仅本机 Desktop 逻辑页,需要同时声明并获批 `agent.tasks: true` 与独立的 `agent.targets: true`)。先检查 `typeof cindy.targets?.list === 'function'`;旧客户端没有此入口,不调用私有 IPC 或自动改投别处。Host 只提供查询、解析和投递;选择 UI、临时选择及固定目标配置由插件自己维护。独立权限 `agent:targets` 会在既有安装/更新确认中展示;旧 tasks 批准和历史未知字段不授予目标访问。缺新批准只阻止新接口,首次调用复用既有宿主确认,不影响旧插件能力。
++
++- `list({targetKind:'project'|'task'|'bot'})`:返回 `{targets:[{kind,id,label,detail}]}`,只含本机可用目标的名称和目录/说明,不含消息历史。插件可自行搜索和展示列表,最近活动只用于排序。
++- `resolve({target:{kind,id}})`:复核已保存或本次选择的目标,返回最新 `{kind,id,label,detail}`。只查询,不创建任务、不打开 UI、不保存绑定;固定目标失效返回 TARGET_UNAVAILABLE,不自动替换。插件可将 `{kind,id}` 存入自己的配置。project 的 id 是 Cindy 已有项目目录,task/bot 的 id 是任务/伙伴标识。
++- `send({target:{kind,id},requestKey,text,title?,route?,delivery?,attachments?})`:直接指定目标,Host 当次复核。project 在目录中新建普通任务,可传统一模型目录的 route;task/bot 沿用接收方模型、权限、目录,不接受 route。`delivery` 为 `queue | steer`,缺省 queue;project 不接受 steer。steer 尝试同轮注入,不停止当前轮,空闲或插话暂不可用时入队。返回 `{taskId,accepted:true,delivery:"queue"|"steer"}` 表示实际接受路径,不表示执行完成。筛查拒绝返回 DELIVERY_REJECTED,不入队重试;ACK 未知返回 DELIVERY_UNCERTAIN,不得换键重发。不开放读取任意任务历史或改模。
++- 同一次 send 重试沿用相同 requestKey、target、内容和 delivery(缺省与 queue 等价);同键参数变化返回 REQUEST_KEY_CONFLICT。Host 在执行前持久保留投递回执,重启后已接受的请求返回原结果,未确定结果的请求返回 DELIVERY_UNCERTAIN,不再次创建或投递。回执不保存正文或附件字节。不要通过更换 requestKey 绕过未知结果,应先让用户在 Cindy 检查。
++- `cancel({requestKey})`:使本次请求及迟到的发送失效,仅撤回本插件该请求尚未执行的输入;不会停止接收方其他输入,也不保证撤销已经开始的工作。新操作使用新的 requestKey。
++- `tasks.send` 和 `targets.send` 均支持可选 `attachments:[{base64,name?}]`:只接收插件提供的图片字节,不接受本机路径、URL、媒体 URI 或自报 MIME。Host 检测 PNG/JPEG/WebP,最多 4 张、合计 20 MiB。先检查 `tasks.capabilities().messageAttachments.kinds` 包含 image;旧客户端不支持时停止,不静默丢图或改投临时路径。截图进既有 cindy-media,作为消息附件展示并进入模型输入;不需要额外声明 media.deposit。附件内容及名称参与幂等签名,更换附件不能复用同键。
++- 目标只包含本机可见、可用的项目、普通任务或有唯一 canonical 对话的活跃伙伴;不提供 Mobile/device-link 透传。投递仍受当前插件启用、批准、账号和目标权限约束;插件内容不构成新真人授权。
++
++原有 `cindy.tasks` 的归属限制不变。先调用 `capabilities()` 获取实际支持操作。当前仅支持本插件创建的本机普通任务:
+ `models`、`create`、`get`、`setModel`、`list`、`send`、`getRun`、`listRuns`、`readMessages`、`cancel`、`setHidden`。
+ 可对自有任务调用 `startTeam({taskId})` 启用 Orca 主任务,并用 `getTeam({taskId})` 读取实际协同状态。协调主任务需经用户授权 Auto,Worker 自动沿用 Auto。
+ 这些任务及其 Worker 不提供 `cindy_helper` 的账号级历史或跨任务控制能力,`cindy_memory.session_search` 也拒绝历史检索;协调使用独立 Orca 工具,结果由插件通过 `readMessages/getTeam` 读取。旧 errand/workspace 不因来源标记受到限制;明确卸载撤销归属后,调用方已无正在执行的输入或已接受新真人输入时,保留的用户任务恢复普通 helper 与历史检索能力;仍执行旧插件输入时继续受限,自动回报和插件输入重试不构成真人接管。这不恢复插件控制权,也不保证停止已接受执行,不构成通用执行沙箱。
+ 在首次派发前调用 `setTeamPlan({taskId,plan:{concurrency,task,items}})`,每项包含
+ `label, workingDir, route, task`。可选 `task` 是插件提供的工作范围(每段最多 8000 字符),
+ 不是用户原话。Host 核对已批准启用的插件、自有主任务、真实 Worker 归属、模型和目录后,
+ 将范围单独交给 Auto 审阅。进入 Host 审批的动作逐次核验用户限制、撤权和只读设置。
+ 首版保留 Codex 原生 Auto;其常规工作区动作可能直接执行,不保证每个动作都经过 Host 范围审批。
+ 卸载会撤销插件后续 API 控制,但不保证停止已派发的原生工作;需要停止时请使用任务停止入口。
+ 计划须在首次派发或创建 Worker 前登记,之后不可改写(包括补填 task);需要不同范围时创建新任务。
+ 缺少该字段的存量计划继续可读,但 Host 不允许插件任务自动授权或普通 MCP 快捷放行,不会从 Agent 消息推导额外授权;进入 Host 的 Ask/acceptEdits 动作仍可沿原流程逐次确认。
+ 计划不授予目录权限。Worker 仅可使用宿主任务目录及解析后仍在其中的子目录、插件 AI 配置目录或用户亲选的确切目录;Library 绑定不自动变成 Agent 工作根。宿主在登记和创建时均复核。
+ 插件自有主任务不支持用 `execution_device_id` 新建跨设备 Worker;本机目录授权不代表已授权另一台电脑的同名目录,登记团队计划也不改变此限制。
+ 这描述准入检查,不是持续的 OS 目录隔离保证。首版用于可信本地工作区;同权限进程在检查后恶意置换目录对象仍可能改变实际 cwd,不提供此类对抗性沙箱。
+
+ `models()` 返回统一目录可选项的完整 route、efforts 和 supportsFastMode。用户明确选择后将 route 原样传给 create,或用 `setModel({taskId, expectedRevision, route})` 修改已有自有任务。运行中按普通任务的安全边界切换,不修改应用默认。两方法使用前检查 capabilities.operations。
+ 当 `capabilities().pluginDefaultModel === true` 时,持续复用任务的插件可在每次新输入前调用
+ `setModel({taskId, expectedRevision, route:'plugin-default'})`。Host 当次读取本插件的任务模型设置,
+ 复用 create 的模型解析规则(未指定时采用当前新任务选择),只同步模型、来源、引擎、强度和 Fast,
+ 不改权限、目录或其它任务。返回 `{status,task}`;配置相同返回 unchanged,不反复切换。
+ 后续 send 使用返回 task.revision。须先处理已接受/结果不确定的旧请求,再同步下一次输入,
+ 不得修改旧请求的回执或为模型变化重发。旧 Host 未声明此能力时保留原任务行为,不传入该 route。
+ 暂不支持接管任意现有任务、远程/伙伴任务、其它配置修改、归档、队列暂停或事件订阅。
+ 旧 `agent.errand` 接口不变。
+
+ **后台任务(可选,需声明 `hiddenTasks`)**。任务默认可见。只有身份卡写了
+ `"agent": { "tasks": true, "hiddenTasks": true }`(详情页与安装/更新确认中单列一项权限),
+ 插件才能把**自己创建的**任务放到后台:不进任务列表、会话搜索、未结束提示、新任务通知与灵动岛,
+ 手机任务列表同样不显示。它不改变任务权限、模型或执行方式,也不授予其它任务的访问权。
+ 未声明时 `create({hidden:true})` 与 `setHidden` 返回 `PERMISSION_DENIED`;
+ `capabilities().hiddenTasks` 表示当前插件是否已声明。用户始终可以在插件详情页「后台任务」
+ 看到这些任务、打开查看,或「显示到任务列表」接手;插件被卸载时它们会自动恢复显示。
+ 请把后台任务用于用户不需要逐条关注的批量/辅助工作,并在插件界面说明它们在哪里能找到。
+
+ ```js
+ const caps = await cindy.tasks.capabilities();
+ const bg = await cindy.tasks.create({ requestKey: 'grade-42-create', title: '批改第 42 份作答',
+ hidden: caps.hiddenTasks === true }); // 未声明时退回默认的可见任务
+ // bg.hidden === true;get/list 快照都带 hidden 布尔值。hidden 参与 requestKey 的幂等摘要。
+ await cindy.tasks.send({ taskId: bg.taskId, expectedRevision: bg.revision,
+ requestKey: 'grade-42-send', text: '按评分标准批改并给出分数。' });
+ // 出现需要用户处理的问题时,把它显示到任务列表(与用户在详情页点击效果相同):
+ await cindy.tasks.setHidden({ taskId: bg.taskId, hidden: false });
+ ```
+
+ ```js
+ // requestWriteAccess({taskId, mode: 'auto'}) 请求宿主原生确认,不能替用户确认。
+ // 拒绝或失败后,同一账号代际/安装修订/任务在当前宿主进程不再自动弹窗(更换 mode 也不重置)。
+ // 用户可从本机任务权限菜单“重新确认插件写权限”恢复原请求;插件不能清除拒绝记录。
+ // 省略 mode 保留 acceptEdits;Auto 插件主任务的 Worker 使用 Auto,不改全局权限。
+
+ const task = await cindy.tasks.create({ requestKey: 'experiment-1-create', title: 'My evaluation' });
+ const run = await cindy.tasks.send({ taskId: task.taskId, expectedRevision: task.revision,
+ requestKey: 'experiment-1-send', text: 'Read the project and report your findings.' });
+ const status = await cindy.tasks.getRun({ runId: run.runId });
+ const page = await cindy.tasks.readMessages({ taskId: task.taskId, limit: 50 });
+ // 保存 nextCursor;下一页传 after,不以最后一条 assistant 推断 run 已完成。
+ ```
+
+ SDK 成功返回 data,失败抛出带 code 的错误。原始管子响应为 `{ok:true,data}` 或
+ `{ok:false,error:{code,message,retryable}}`。不要将请求键换掉来绕过不确定的派发结果。
+ create/send 的 requestKey 持久去重;同键不同内容拒绝。删除后的记录不自动重建。
+ 请求键及 taskId/runId 需要由插件保存。取消仅作用于该输入,不能停止用户后来的执行。
+
+ 省略 route 时使用用户给本插件的任务模型覆盖;无覆盖则沿用发起任务,面板直接创建时
+ 沿用当前新任务选择。可显式传
+ `{agentKind:'codex',providerId:'...',model:'...',effort:'high',fastMode:false}`;无推理档位模型用空 effort。
+ 先查 `capabilities().sourceCallContext`:支持时,Agent 在途调用可在 create 中转传 `callId`。
+ 宿主核对同插件本机调用后读取其模型;不能自报 sourceSessionId 或权限。面板直接创建省略 callId。
+ 新字段需该能力为 true 才发送,旧客户端不能假定支持;同 requestKey 的重放保留原创建结果。
+ 来源/模型/强度必须当前可用,派发前再次核对;失败引导改选或修复连接,不自动换模型或账号。
+ 已有普通任务保留自身配置,用户在任务内修复后继续使用原任务。
+ 工作目录由宿主分配,或沿用用户已在插件设置中选择的目录;不接受任意路径或权限覆盖。
+ 权限来自用户的插件任务设置,缺省使用普通任务的 ask 权限;工作区内行为及询问规则与所选
+ Agent 的普通任务一致。允许用户显式选择 acceptEdits / auto,禁止 bypassPermissions,
+ 不继承发起任务的权限。既有任务与显式历史 plan 配置保留原行为,不自动提权;需要改变时由用户选择。
+ create 可传 `isolatedWorkspace:true`,使用宿主为该任务生成的独立空目录,忽略插件的项目目录偏好。
+ 返回 workingDir 仅属于本插件创建的任务,可交给插件 Node 进程放入候选项目;不接受插件自报任意目录。
+ 任务视图同时返回 permissionMode;按实际权限展示,不将历史 plan 值视作跨 Agent 的只读保证,不能暗中升级权限。
+
+ run 的 acceptedConfig 是接收配置,execution 是观测到的原生 instance/generation,
+ 不冒充完整实际用量/重试清单。outputMessageId 来自产品终态,不是文字猜测。
+ 没有足够证据的重启/恢复窗口返回 reconciling,不能当 completed、failed 或零分;
+ 不要自动重发可能已经产生副作用的输入。费用目前 unavailable,绝不以耗时推算。
+ 实验性接口尚未提供全部恢复路径的最终对账和事件补拉,因此暂不用于无人值守正式评测。
diff --cc apps/desktop/resources/system-skills/cindy-plugin-creator/references/plugin-manifest.md
index 0000000000,5aa5009657..b30a18b513
mode 000000,100644..100644
--- a/apps/desktop/resources/system-skills/cindy-plugin-creator/references/plugin-manifest.md
+++ b/apps/desktop/resources/system-skills/cindy-plugin-creator/references/plugin-manifest.md
@@@ -1,0 -1,355 +1,358 @@@
+ ## 2. ghost.json 身份卡
+
+ ```json
+ {
+ "schemaVersion": 3,
+ "id": "my-ghost", // 小写字母/数字/连字符,1–32 位,全局唯一
+ "name": "我的插件", // 展示名
+ "description": "一句话说清这个插件是干嘛的(给人看:插件详情页)", // 1–300 字
+ "whenToUse": "需要生成图片、插画、配图、修图、P 图、改图时找我", // 1–300 字,给模型看:进 agent 会话的插件花名册,是"用户不点名时 AI 能不能想起你"的关键。写成场景枚举,可反复调优;花名册会折叠连续空白,异常数据会截断;缺省时花名册回落用 description
+ "icon": "assets/icon.png", // 建议:插件图标(包内相对路径;扩展名限 png/jpg/jpeg/webp/gif,不收 svg——svg 可携带脚本,虽经 <img> 渲染不执行,仍不给这个面)。不配则面板与消息身份头显示默认拼图占位符;官方插件仓惯例放 assets/icon.png
+ "locales": { // 可选:插件只跟随宿主语言;不支持/缺失语言固定回退 en
+ "en": "locales/en.json",
+ "zh-CN": "locales/zh-CN.json",
+ "ja": "locales/ja.json",
+ "ko": "locales/ko.json"
+ },
+ "version": "1.0.0",
+ "minCindyVersion": "1.2.3", // 示例;v3 必填:本插件实际依赖的首个 Cindy 正式版本(SemVer)
+ "entry": "main.js", // 电子脑入口(kind 字段已无需填写:插件只有芯片一种形态,缺省即 chip;写了也只认 "chip")
+ "launch": "on-demand", // 可选:电子脑启动模式。on-demand(缺省)=被需要才拉起;resident=唤醒即常驻(详情页会如实标注"常驻运行",绝大多数插件不需要,仅订阅型/需秒响应的场景用)
+ "command": "画图", // 推荐:用户 $画图 显式点名(与已装插件查重,冲突拒装)。
+ // 注意:不声明 command 时,插件页"使用"按钮将处于禁用状态——用户无法通过插件页
+ // 一键启用/唤起插件,也不能用 $command 显式点名;但 AI 的工具发现与调用不受影响
+ // (仅检查插件启用状态与 tools 声明)。除非你的插件完全靠 panel 或 subscribe 驱动,
+ // 否则请始终声明一个 command。
+ "tools": [ /* 见 §3 */ ],
+ "cindy": { "image": ["generate", "edit"] }, // 直接声明能力及详单,见下
+ // 类目按需申请:image / video 的动作是 "generate" | "edit";media 只有
+ // "deposit"(把你手里的媒体字节寄存进总仓换指纹,见 §4.0.1);
+ // text 只有 "oneshot";search 只有 "web"(Cindy 托管公网搜索)。每条都会
+ // 在插件详情的能力清单里单独列给用户看。
+ "panel": { "title": "面板标题", "html": "panel.html", "position": "left",
+ "minWidth": 240, "defaultFraction": 0.24,
+ "systemButtons": { "maximize": false } },
+ // panel.position:面板显示形态。left(缺省)/ right / top / bottom = 右侧栏常驻面板:
+ // 启用后自动成为聊天区对应边页签组里一个不跟对话的全局页签(切任务保留、可最大化、
+ // 可弹成独立窗口、用户可拖到任何一边或关闭;用户放置过后主机记住用户的位置,
+ // 你的声明只是首次出现时的默认);"tab" = 插件页内的独占面板(用户在插件页点插件卡的
+ // 「使用」打开,离开插件页即关闭;同一时刻至多一个;此形态没有拖缝宽度,声明 minWidth /
+ // defaultFraction 会被拒装,请移除)。minWidth / defaultFraction 仍可声明(兼容),当前
+ // 页签组宿主不消费。
+ // panel.systemButtons(可选):历史字段,保留兼容、当前不生效(右侧栏页签的
+ // 关闭 / 最大化 / 弹出按钮由主机统一提供);position:"tab" 时声明本字段拒装
+ // 一级主视图是独立能力,见 §4.20。使用时直接声明:
+ // "mainView": { "title": "工作台", "icon": "puzzle", "html": "main-view.html" }
+ // 可选 "open": "page"(缺省,撑满内容区)/ "sidebar"(作为页签进聊天区某一边,配 "side":
+ // left / right / top / bottom)/ "window"(弹成独立窗口);只是左侧导航入口的默认打开方式,
+ // 用户拖过 / 弹过后以用户的放置为准。可选 "multiple": true 允许同一视图同时开在多处。
+ "settingsHtml": "settings.html", // 可选:设置页「自定义设置区」自绘界面(见 §4.8;声明了用户填的凭证时仍必填,用于长期管理/替换/清除;调用前缺失时主机也会在统一 Setup 卡内联收单,见 §4.7)
+ "showTaskPreferences": true, // 可选:是否显示宿主「模型与任务」卡,缺省/true 显示,false 隐藏;见 §4.8
+ "settingsHeight": 360 // 可选:固定高度 px(160–800);缺省 = 随内容自适应(矮内容真收矮,高至 800);内容会动态增减时才声明,避免抖动
+ }
+ ```
+
+ `schemaVersion: 3` 必须填写 `minCindyVersion`。它写本插件实际依赖的首个 Cindy
+ 正式版本;Manifest schema 本身没有统一的 Cindy 版本下限。不要为了使用某项既有能力随意抬高版本。
+ 官方市场会优先向旧客户端投影最近的兼容历史版本,没有兼容版本时不展示该插件。
+ Desktop 信任来源已经完成的版本选择,不再按 `minCindyVersion` 追加筛选或确认弹窗;
+ 用户主动导入的本地包、以及用户添加的自定义市场也遵循同一安装策略。这个字段仍必须
+ 准确填写:它供发布服务选择兼容 release,也记录插件真实依赖的首个 Host 版本。
+
+ ### whenToUse:只写发现线索,不写使用规则
+
+ 在作者契约里,`whenToUse` 是专门给模型做插件发现与判断的唯一字段;
+ `description` 给人看(插件详情页),不要拿它兼任模型路由说明。
+ `whenToUse` 最多 300 字符,花名册会完整展示有效内容,折叠连续空白并对异常数据做防御性截断。花名册命中已知 `ghost_id` 时用
+ `ghost_info` 精准现查单条;未命中或需要全量实时回查时用 `ghost_list`。两者都返回完整
+ `CindyGhostInfo`,取得信息后再按任务交叉读取 Manual 与插件工具目录,信息足够即可调用。
+ 未声明 `whenToUse` 时宿主会用 `description` 兼容回落,但高质量插件
+ 必须单独写好 `whenToUse`,不要依赖回落。
+
+ 只写用户意图、业务对象和常见说法的**场景枚举**,回答"什么情况下应该想到这个插件"。
+ 禁止塞入"必须/不得"式行为规则、工具调用顺序、参数协议、错误码与重试策略。
+ 单个工具怎么调用放进工具及参数 `description`;同一类别内、紧贴当前工具集合与参数的
+ 动态规则放进 §3.5 的 **`list_tools(category)` RULES**;多工具组合、跨类别完整流程、
+ 长期稳定的共同原则与深入用法放进 §3.6 的 Manual。不要在三处复制同一份规则。
+
+ 反例(错把使用规则塞进发现面):
+
+ ```json
+ "whenToUse": "管理项目时找我;必须先调用 list_tools(category=project),再调用 call_tool;遇到 INVALID_ARGS 不得改用其它工具"
+ ```
+
+ 改正版(只保留场景枚举):
+
+ ```json
+ "whenToUse": "需要查询、创建或更新项目、任务、成员、迭代与发布状态时找我"
+ ```
+
+ ### 2.1 本地化资源(locales)
+
+ 插件语言**只跟随 Cindy 宿主当前语言**。不要读取 `navigator.language`、操作系统语言或
+ 浏览器偏好,也不要在插件内保存另一份语言选择。宿主当前支持
+ `zh-CN / en / ja / ko`;插件没提供宿主当前语言时固定使用英文,因此只要声明
+ `locales` 就必须提供 `en`。
+
+ locale JSON 覆盖清单中已有的可本地化字段。**翻译是可选项**:提供的条目必须合法,
+ 未提供的条目在运行时回退原 manifest 文案(通常是英文);完整翻译(含每个工具参数
+ 的 title / description)是高质量插件的推荐标准,但不是打包/装入门槛。工具按稳定的
+ tool name 对齐,协议键、工具名和参数名不翻译:
+
+ ```json
+ {
+ "name": "My Plugin",
+ "description": "What this plugin does.",
+ "whenToUse": "Use it when ...",
+ "tools": {
+ "do_thing": {
+ "description": "Do the task and return the result.",
+ "parameters": {
+ "/properties/query": {
+ "title": "Query",
+ "description": "Describe what to search for."
+ }
+ }
+ }
+ },
+ "panel": { "title": "Plugin panel" },
+ "mainView": { "title": "Workspace" },
+ "network": {
+ "secrets": {
+ "api_key": { "label": "API key", "hint": "Create one in account settings." }
+ },
+ "connections": {
+ "instance": { "label": "Service instance", "hint": "Enter the instance URL and token." }
+ }
+ },
+ "node": {
+ "secretBindings": {
+ "worker_key": { "label": "Worker key", "hint": "Used only by the local worker." }
+ }
+ },
+ "setup": {
+ "kv": {
+ "default_repo": { "label": "Default repository" }
+ }
+ }
+ }
+ ```
+
+ 可翻译字段:`name`、`description`、`whenToUse`、`tools`(工具 description 与参数
+ 文案)、`panel.title`、`mainView.title`、`network.secrets / connections`、`node.secretBindings`、
+ `setup` 的 kv 标签;凭证、连接、Node 凭证和 kv 项按稳定 key 对齐(提供某个 key 的
+ 条目时 label 必填,hint 可选)。工具参数 schema 中已有的 `title / description` 用
+ JSON Pointer 对齐(如 `/properties/query`;根节点用空字符串 `""`),参数名、类型、
+ 枚举和协议结构不翻译。缺译不拒绝,只回退原文;但**翻译错位仍是硬错误**——未知
+ key、未知字段、原清单没有的条目、类型或长度不合格、文件缺失、路径大小写与磁盘
+ 不一致、无效 JSON 或单文件超过 64KB 都会在 Forge 打包期、内置播种期与安装期拒绝。
+ 清单列表、详情页、Panel 标题、安装/配置提示和 Agent 工具目录都消费同一份本地化结果。
+
+ 所有会作为对象索引的稳定标识——tool name、network secrets / connections key、
+ node secretBindings key、setup kv key——都不能使用 `__proto__`、`constructor` 或
+ `prototype`;这些名称是宿主保留键,打包时会直接拒绝。
+
+ v3 直接用顶层字段声明插件贡献项与自主 Host 能力,不再有 `slots`。带详单的字段是 `tools`、`cindy`、
+ `agent`、`panel`、`mainView`、`card`、`subscribe`、`network`、`node`、`preview`、
+ `skill`;布尔能力写成字面量 `true`:`notify`、`badge`、`confirm`、`fs`、
+ `library`、`sessionContext`、`pick`、`workspace`。不用的字段直接省略,
+ 邮件插件声明 `mail: true`,调用 Cindy 内置 `cindyMail.register(adapter)`
+ (version 1),不生成卡片 HTML、不打包公共流程;纯邮件插件不需要 `card`。
+ 阅读邮件可声明 `mailReader:{tool,hosts}`,工具接收 `{url}` 并返回 MailMessage,默认只读。
+ `mail` 只能省略或写字面量 `true`;声明 `mailReader` 时必须同时有 `mail: true`,
+ 且 `tool` 必须指向本清单 `tools` 中的工具。协议校验与桌面安装校验都会拒绝不完整组合。
+ 支持打开即已读时增加 `mailReader.markRead:true`,读取工具接受可选 `markRead:true`;
+ 声明中的 `markRead` 只能省略或为字面量 `true`,`false`、字符串等其它值不合法。
+ 仅用户主动打开时传入,AI 读取和邻近预加载不传。成功读取后只标记当前邮件,不标记整个会话或草稿。
+ Host 派发器会移除普通工具参数中的此标记,仅可信阅读器打开请求可注入;其它明确授权的已读操作工具不受影响。
+ 标记失败仍返回正文和 `markReadFailed:true`,由 Cindy 显示提示;新增 OAuth scope 不阻断已有授权的操作。
+ 适配器提供 providerName、draftStorage(server/local)、selectAccount、readDraft、writeDraft。
+ 通过 present 展示读回草稿,beforeTool 统一 get/send/update/delete,resolveDraft 获取最新位置。
+ Host 负责样式、编辑同步、发送和任务续接;同一任务同一封邮件只显示最新卡片,旧快照保留但不重复展示。插件保留凭据、MIME 和服务商请求。
+ 插件重启后,下一次卡片编辑或工具操作会自动读回原草稿,使用 Host 卡片中上次同步的内容、卡片编辑和邮箱最新内容做三方合并;单边变化、相同变化和不重叠的文字修改自动合并,只有无法合并的修改才保留两边内容并提示具体字段。版本标记或预览地址变化本身不算冲突。适配器返回 execution:not_executed 和 stale 读回快照时可合并后重试一次,未知操作结果不能重试。发送倒计时结束时若发现实际内容变化,展示合并稿并重新倒计时。
+ 图文适配器的 attachmentItems 可为已有图片 key 添加 contentId,表示将同一附件插入 HTML 正文;必须核验实际图片字节、保留 MIME 引用,不能重复上传或把预览 URL 写入邮件。
+ 工具说明应要求默认展示草稿卡等用户确认;只有用户已明确确认该邮件,或有效的用户/任务指令明确授权该范围内直接发送,才不再询问。写信/回复请求、编辑及自动审批本身不代表确认。
+ UI 和 Agent 发送都先进入 10 秒倒计时,卡片可撤销或立即发送;beforeTool(send) 等待最终回执。
+ 撤销后保留草稿且不得自动重试。所有发送先创建并展示草稿,再走 beforeTool(send),不得保留直发旁路。
+ 缺少 SDK 时只读可用,编辑/发送需更新 Cindy;不要绕开公共流程直接发送已展示草稿。
+
+ 不能写 `false`。`card: {}` 与 `agent: {}` 分别表示基础聊天卡片能力和用户点击后
+ 发起 Agent 回合;其它对象型能力必须包含该能力真正需要的详单。
+
+ v3 未识别的顶层字段会原样保留,但旧版 Cindy 不展示、不给这个未知 Host 能力、也不因此阻止安装。
+ 当未来 Cindy 识别该字段后,它才会进入正常的能力展示与运行时守门。插件若依赖新能力,
+ 应同时把 `minCindyVersion` 提高到首个支持版本;仅由插件包自己完成的逻辑不要发明
+ Host 能力字段。v2 的 `slots` 只用于存量包兼容,新插件不得再写。
+ 当前 Agent tool-call 内,插件工具是否执行由外层 `ghost_call` 的 Agent 授权决定;
+ 普通网络和 workdir 文件操作按上文的 `callId` 绑定复用 Agent 授权。CLI 继续由
+ 已声明运行形态的 Node 工作进程执行,不新增未知 Host 能力或具体命令登记。
+
+ **agent 能力详单**:写 `"agent": {}` 时,默认只允许在用户真实点击你的
+ 聊天卡片后发起一次 Agent 回合。若确实需要没有当次点击也能自动发起,写
+ `"agent": { "background": true }`。后台档会在插件详情中单独显示为更高风险能力,
+ 而且仍只能使用用户曾通过点击卡片与你建立关联的会话。
+ 要把任务交给 Agent 干并**取回结果**(而不是发进用户的会话),另写
+ `"agent": { "errand": true }`(可与 background 并存),见 §4.11.1;同样是详情页
+ 单列的高风险档。
+ 要请用户新建一条**自动化**(让插件里的内容定期自己刷新),另写
+ `"agent": { "schedule": true }`(可与前两项并存),见 §4.11.2。它只能打开预填好的
+ 创建面板,任务由用户选好模型后亲手保存才存在;详情页单列一档。
+ 用普通任务接口(§4.11.3)写 `"agent": { "tasks": true }`;需要把自己创建的任务放到后台
+ (不进任务列表、搜索与通知)时再加 `"hiddenTasks": true`,它必须与 `"tasks": true` 同时
+ 出现,否则拒装;详情页单列一档。
++向项目、已有任务或伙伴投递内容时另声明 `"agent": { "tasks": true, "targets": true }`(§4.11.3)。
++`targets` 是独立权限,安装/更新确认单列,需 Host 显式批准;旧 tasks 批准不授予目标访问。
++新包的 targets 必须是布尔值,targets:true 缺 tasks:true 时拒装。
+
+ **node 工作进程详单**(声明 node 时必写,详见 §4.12):
+
+ ```json
+ "node": {
+ "entry": "node/worker.cjs", // 包内 CommonJS 入口,只认 .js/.cjs
+ "protocol": "json-rpc-stdio", // json-rpc-stdio / mcp-stdio
+ "lifecycle": "on-demand", // 可选:on-demand(缺省)/resident(常驻,单列高风险权限)
+ "idleTimeoutSeconds": 120, // 可选:按需档空闲关闭时间,30–3600;resident 禁写
+ "entries": ["node/build.cjs"], // 可选 ≤4 条:额外工作进程入口(每入口一个独立进程,调用时用 entry 指名,见 §4.12.1;不能与 entry / 浏览器沙箱 entry / 彼此重复)
+ "childSpawn": true, // 可选:worker 可请宿主代启申报入口的原样 stdio 子进程(见 §4.12.4;详情页单列一行)
+ "secretBindings": [{ // 可选 1–4 条:safeStorage 持久化凭证按方法临时注入 Worker
+ "key": "mail_code", // 插件内唯一,小写字母开头,1–32 位小写/数字/下划线;禁用宿主保留键(见 §2.1)
+ "label": "邮箱授权码", // 详情页与设置页展示名
+ "methods": ["mail/action"], // 只在这些 JSON-RPC 方法中注入,每条 1–128 位
+ "entry": "node/worker.cjs", // 可选:逐字命中 node.entry/entries;缺省仅主入口
+ "hint": "请填写服务商授权码", // 可选 ≤200 字
+ "url": "https://mail.example.com/settings" // 可选 https 申请页
+ }]
+ }
+ ```
+
+ node 详单**不接受** `command` / `args` / `shell` / `env` 或其它自造字段;
+ 入口固定使用 Cindy 随包运行时启动,用户不需要另装 Node、CLI 或 MCP。
+ **不要在 worker 里用 `process.execPath` / `child_process.fork` 再生 Node 子进程**
+ ——正式包关闭了 RunAsNode,那样生出来的不是 Node;要多进程就把入口申报进
+ `entries`,由主机代开。
+
+ **preview 详单**(声明 preview 时必写,详见 §4.15):
+
+ ```json
+ "preview": {
+ "hosts": ["*.example.dev", "localhost"] // 1–4 条;语法同 network.hosts;能在右侧栏打开的预览网站白名单,详情页逐条展示
+ }
+ ```
+
+ **skill 详单**(声明 skill 时必写,详见 §4.16):
+
+ ```json
+ "skill": {
+ "items": [{ // 1–4 条
+ "dir": "skills/my-skill", // 包内技能目录,内必须有 SKILL.md
+ "name": "my-skill", // 硬规则:与 SKILL.md frontmatter name 逐字一致;小写字母/数字加单连字符分段(禁首尾/连续连字符),≤64
+ "description": "……" // 硬规则:与 SKILL.md frontmatter description 逐字一致(详情页展示的就是 Agent 读到的),1–1024 字
+ }]
+ }
+ ```
+
+ **manual 随包手册**(独立顶层字段,不是 slot、不是权限项,详见 §3.6):
+
+ ```json
+ "manual": {
+ "items": [{ // 1–8 条
+ "dir": "manual/getting-started", // 包内物理目录,必须有 MANUAL.md
+ "name": "getting-started", // ghost_manual path 的逻辑首段,不暴露物理 dir
+ "description": "从安装到首次运行" // 一级轻量索引,1–300 字
+ }]
+ }
+ ```
+
+ **cindy 能力详单**:声明插件要基于哪些 Cindy Core 能力提供上层能力--只有类目和
+ 动作,**没有任何具体模型/供应商信息**。image / video 声明同时决定该插件能否在
+ 自己的设置页或面板读取对应类型的模型目录;生成请求仍由当前 Agent 发起。
+ 类目与动作:`image`(`generate`=出图 / `edit`=改图)、`video`(`generate`=
+ 文生视频 / `edit`=图生视频,参考图怎么用由 `refMode` 决定:首尾帧 1–2 张,
+ 或多张参考图,详见 §4 的 cindy-request 视频段)、`media`(`deposit`=把手里的
+ 媒体字节存进媒体库,§4.0.1)、`text`(`oneshot`=快问快答,§4.0.2)、
+ `embed`(`text`=文本转向量,§4.0.3)、`search`(`web`=Cindy 托管
+ 公网搜索,见 §4 的 `search_web` 段)。
+ 详单里没申请的动作,运行时点单直接被拒。`search.web` 只能由真实 tool-call
+ 触发,还必须同时声明至少一个 `tools` 条目。旧 v2 包的 model slot/字段仍兼容,
+ 但新插件一律使用 v3 的 `cindy` 字段。
+
+ **network 详单**(声明 network 时必写,详见 §4.7):
+
+ ```json
+ "network": {
+ "hosts": ["api.example.com", "*.weather.com"], // 1–8 条;小写域名至少两段;通配只允许最左 "*.";详情页逐条展示给用户
+ "secrets": [{ // 可选 0–4 条:需要用户填的凭证(你只声明名字和注入位置,值用户填、主机保管)
+ "key": "api_token", // 小写字母开头,小写/数字/下划线,1–32;禁用宿主保留键(见 §2.1)
+ "label": "Example API Token", // 给用户看的名称(设置页/详情页)
+ "source": "user", // 可选:凭证值来源。"user"(缺省)=用户可在调用前的主机 Setup 卡内填写,也可在你的 settingsHtml 里长期管理/替换/清除(当前仍要求同时声明 settingsHtml,见 §4.7);"login-email"=主机登录邮箱自动派生(用户不填;声明它时不允许再写 url,见 §4.7);"oauth"=主机托管 OAuth 授权,值 = 授权换来的 access token(必须同时声明 oauth 详单,见 §4.7 与下方 oauth 字段);"gh-cli"=仅官方 cindy-github 可用,优先复用本机 gh 登录、不可用时回落同 key 的设置页 PAT;"oidc-token"=主机为当前企业 Membership 按需签发短时 Connection JWT(插件不可读取,必须显式限制 inject.hosts,固定 Authorization: Bearer {value},见 §4.7)
+ "hint": "在控制台生成后粘贴", // 可选提示(主机 Setup 卡与 settingsHtml 都会用到)
+ "url": "https://example.com/settings/keys", // 可选:控制台/申请地址(仅 https)。调用前缺凭证时,主机 Setup 卡会在输入框旁展示本地化的「获取凭证」入口;settingsHtml 也可用 <a href> 逐字引用它,点击经主机转系统浏览器打开(见 §4.8「外链」)
+ "inject": { // 必填:这条凭证怎么进请求
+ "header": "Authorization", // 注入的请求头名(Host/Cookie 等协议关键头禁用)
+ "format": "Bearer {value}", // 恰含一个 {value} 占位,其余静态文本
+ "hosts": ["api.example.com"] // 可选:注入范围(hosts 声明条目的子集,逐字);缺省=全部
+ },
+ "exchange": { // 可选:key 换令牌二段式(服务要求先拿 key 换临时令牌时声明,主机照单代办,见 §4.7;与 oauth 互斥)
+ "url": "https://api.example.com/token", // 交换端点(https;域名必须命中 hosts 白名单)
+ "bodyFormat": "{\"sub\":\"{value}\"}", // POST 请求体模板,恰含一个 {value}(原始 key 落点,主机按 contentType 转义)
+ "contentType": "application/json", // 可选:application/json(缺省)/ application/x-www-form-urlencoded
+ "tokenPath": "session", // 令牌在响应 JSON 里的点分路径(如 "data.token";值须是非空字符串)
+ "ttlSeconds": 86400 // 可选:令牌缓存秒数(60–2592000,缺省 3600)
+ },
+ "oauth": { // source:"oauth" 时必填(其它来源禁写):主机托管 OAuth 授权详单(见 §4.7)
+ "authorizeUrl": "https://accounts.example.com/authorize", // 授权页(https;域名必须命中 hosts 白名单)
+ "tokenUrl": "https://accounts.example.com/token", // code/refresh 交换端点(https;域名必须命中 hosts)。注:个别服务商(如 xAI)的新版 consent 页不再 302 回 loopback,而是页面 JS 跨源投递授权 code——主机允许的投递来源 = authorizeUrl/tokenUrl 的 origin + hosts 白名单命中的 https 域;consent 页与授权端点不同域时,把 consent 域(如 accounts.x.ai)也声明进 hosts 即可
+ "clientId": "xxx.apps.example.com", // 可选:内置 OAuth 客户端 ID(用户零配置开箱即用;用户在设置页自填的覆盖内置,清除自填即回落)
+ "clientIdAlternatives": ["xxx-global.apps.example.com"], // 可选 ≤8 条:仅 tokenBroker 模式;插件按 app-context 选 App 时,connect 只接受默认值或这里声明的公开 ID
+ "clientSecret": "xxx", // 可选(须与 clientId 成对):内置 client 的 secret;桌面应用的 client 凭证本非机密,纯 PKCE 服务商可省略
+ "scopes": ["read.a", "write.b"], // 可选 ≤256 条:申请的权限范围(详情页逐条展示给用户)
+ "scopeDelimiter": ",", // 可选:authorize URL 的 scope 拼接分隔符;缺省空格(OAuth 标准),Slack 这类逗号分隔的服务商声明 ","(目前只认这一个值)
+ "pkce": true, // 可选:PKCE(S256)开关,缺省 true
+ "extraAuthorizeParams": { "access_type": "offline", "prompt": "consent" }, // 可选 ≤8 条:服务商特有授权参数(协议保留参数禁写)
+ "identity": { "url": "https://api.example.com/userinfo", "labelPath": "email", "displayTemplate": "{team} · {user}", "avatarPath": "data.avatar_thumb" }, // 可选:授权后拉一次身份端点给账号打标签(设置页"已连接为 xxx";url 域名须命中 hosts)。labelPath 应指向**唯一且稳定**字段(如邮箱 / user_id)——它是重复授权时的同身份合并判定键,选 name 这类可重名可改名字段会误合并。displayTemplate 可选:人类可读展示名模板,`{点分路径}` 占位符从同一份身份响应取值(至少一个占位符,≤200 字符),任一占位符取不到值整体降级为空、回落显示 labelPath 的值——labelPath 的稳定字段不可读(如 Slack 的 user_id)时声明它,设置页与账号工具展示的就是渲染后的名字(邮箱这类本身可读的服务商不需要)。avatarPath 可选:头像 URL 在身份响应里的点分路径(如飞书的 "data.avatar_thumb")——主机取 https 地址后**不带凭证**下载小图(仅 png/jpeg/webp/gif、≤256KB)转 data URL 存库,`/oauth` 回查里以 account.avatarDataUrl 给你的 settingsHtml 展示(<img> 直接用)。**下载仅对第一方官方插件生效**(头像地址不受 hosts 白名单约束,第三方声明合法但恒降级 null)——所以页面必须能没头像也好看(如回落姓名首字圆片)
+ "redirectPort": 53682, // 可选:loopback 回调固定端口(1024–65535);声明 tokenBroker 时必填。服务商要求回调 URI 与注册值精确匹配(如 Atlassian)时声明,回调恒为 http://127.0.0.1:<端口>/callback;非 broker 模式缺省 = 随机端口(Google 等允许任意 loopback 端口的服务商不用声明)
+ "tokenBroker": "jira", // 可选:三路资格:随包官方种子或受信任公开市场的官方插件(名称本身不构成资格);当前组织的服务端 organization market 包满足来源/组织/namespace/整包 sha256 绑定;或企业作者用 ghost_forge_install 明确安装到当前组织 namespace。后两路只给 Broker 与 oidc-token,不给宿主原语;手动导入与个人身份不放行。声明时必须同时声明 redirectPort;code/refresh 交换经 Cindy 服务端 broker 完成(client secret 在服务端,不随包分发),与 clientSecret 互斥;设置页不再支持自填 client
+ "brokerBounce": { "path": "/example/bounce", "callbackPath": "/example/callback" } // 可选:双地址弹跳回调(服务商后台只收 https redirect、不收 http loopback 时用)。必须与 tokenBroker、redirectPort 同时声明;报给服务商的 redirect_uri = broker 服务基地址 + path(主机运行时拼,清单不落域名),浏览器授权后由弹跳路由 302 回 http://127.0.0.1:<redirectPort><callbackPath>
+ }
+ }],
+ "connections": [{ // 可选 0–2 条:多连接声明——"地址 + 凭证成对多条"(自建实例场景如 GitLab,详见 §4.7「多连接」)。声明了 connections 时 hosts 可缺省/为空(静态域名与动态连接至少有其一);声明 connections 必须同时声明 settingsHtml
+ "key": "gitlab", // 小写字母开头,小写/数字/下划线,1–32;禁用宿主保留键;与 secrets[].key 共用命名空间,撞名拒装
+ "label": "GitLab 实例", // 给用户看的连接类型名(1–64 字;详情页与设置页展示)
+ "hint": "填实例域名与 Personal Access Token", // 可选 ≤200 字提示(建议写进你的 settingsHtml 文案)
+ "inject": { "header": "Private-Token", "format": "{value}" }, // 凭证注入形态(规则同 secrets 的 inject);**不允许**声明 inject.hosts——凭证恒只注入对应连接自身的地址,写了拒装
+ "maxConnections": 4 // 可选:每种连接可添加的地址数上限(1–8 整数,缺省 8)
+ }]
+ }
+ ```
+
+ **setup 就绪声明**(可选,顶层字段):回答"这个插件**用之前必须配好什么**"。用户在
+ 插件页点「使用」或 Agent 调用你的工具时,主机按它做前置检查;没配齐就用统一设置卡
+ 引导用户完成配置:普通 user Secret 直接在卡内填写,OAuth 在卡内发起授权,KV 与连接等
+ 复杂配置再进入插件详情页。普通任务配齐后继续原调用;伙伴会保留独立授权卡并结束当前轮,
+ 授权完成后由主机通知伙伴继续原工作。没有图标时不生成占位图标,插件已有配置面板与成果
+ UI 保留。检查、字段绑定、保存状态和恢复都在主机
+ 代码里执行,你只声明需求,不用写卡片回调或检查逻辑,也不要在电子脑里自己重复检查。
+
+ ```json
+ "setup": {
+ "requires": [ // 0–8 组;组间全部满足(allOf),组内任一满足(anyOf);空数组 = 显式声明"无使用前置需求"(恒就绪,见下)
+ { "anyOf": ["secret:brave_api_key", "secret:tavily_api_key"] }, // "两个 key 任一配好即可"
+ { "anyOf": [{ "kv": "default_repo", "label": "默认仓库" }] } // kv 参数用对象形态,label 必填(弹窗展示名)
+ ]
+ }
+ ```
+
+ - 条目三种引用:`secret:<key>`(`network.secrets` 或 `node.secretBindings` 声明的
+ 凭证:Node 绑定与 user 源查已保存、oauth 源查已连接账号;账号全过期时主机弹「重新连接」
+ 话术)、`connection:<key>`(该连接声明下至少添加一条)、
+ `{ "kv": "<键名>", "label": "..." }`(你 /kv 参数里的顶层键非空且不能是宿主保留键;键名主机无先验,
+ label 必填)。Node 凭证同样可参与 setup.requires。
+ - 引用必须逐字指向已声明的 key,悬空引用**打包期就拒**;`login-email` /
+ `gh-cli` / `oidc-token` 这类 Host 派生或优先来源不允许引用(没有可靠的
+ 同步配置动作可引导)。kv 引用要求已声明 settingsHtml(没有设置页没人填)。
+ - **绝大多数插件不需要写本字段**:不声明时主机走启发式——声明过凭证/连接的插件,
+ 任一项配好即算就绪;什么都没声明的恒就绪。只有启发式判不准才需要显式声明,两种
+ 典型:"必须**同时**配 A 和 B"(多组声明)、"凭证全是**可选项**、一个不配也能用"
+ (写 `"setup": { "requires": [] }` 显式声明无前置需求,主机不再用启发式拦你)。
+ - 检查只管**存在性**(配没配),不管有效性(key 对不对)——填错 key 仍会在真正调用时
+ 由主机网络层报错,你的工具逻辑照常处理失败即可。
diff --cc apps/desktop/src/main/maker-host/built-in-skills.ts
index 6e8f024dc5,debaa7d52d..671bb841f6
--- a/apps/desktop/src/main/maker-host/built-in-skills.ts
+++ b/apps/desktop/src/main/maker-host/built-in-skills.ts
@@@ -23,7 -25,8 +25,8 @@@ const VERSIONS_DIRECTORY = '.versions'
const ACTIVE_BUNDLE_LINK = '.active';
const BUILT_IN_SKILL_MUTATION_WAIT_MS = 5_000;
/** Increment whenever shipped built-in Skill bytes change between releases. */
- export const BUILT_IN_SKILLS_BUNDLE_VERSION = 12;
-export const BUILT_IN_SKILLS_BUNDLE_VERSION = 14;
++export const BUILT_IN_SKILLS_BUNDLE_VERSION = 15;
+ const PLUGIN_CREATOR_FIRST_BUNDLE_VERSION = 13;
export interface BuiltInSkillDescriptor {
name: string;