@ftai/plugin-host-api 2.0.0 → 2.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (47) hide show
  1. package/lib/attachments.d.ts +112 -1
  2. package/lib/capabilities.d.ts +99 -0
  3. package/lib/capabilities.js +21 -0
  4. package/lib/cmdline.d.ts +52 -0
  5. package/lib/cmdline.js +68 -0
  6. package/lib/credentials.d.ts +92 -0
  7. package/lib/credentials.js +41 -0
  8. package/lib/fs.d.ts +69 -5
  9. package/lib/generated.d.ts +3935 -316
  10. package/lib/generated.js +66 -6
  11. package/lib/index.d.ts +365 -69
  12. package/lib/index.js +44 -3
  13. package/lib/jobs.d.ts +88 -0
  14. package/lib/jobs.js +2 -0
  15. package/lib/llm.d.ts +124 -21
  16. package/lib/llm.js +45 -3
  17. package/lib/local-install.d.ts +38 -0
  18. package/lib/local-install.js +9 -0
  19. package/lib/permissions.d.ts +97 -0
  20. package/lib/permissions.js +11 -0
  21. package/lib/platform.d.ts +167 -0
  22. package/lib/platform.js +74 -0
  23. package/lib/porting.d.ts +23 -7
  24. package/lib/porting.js +692 -67
  25. package/lib/prompt.d.ts +117 -0
  26. package/lib/prompt.js +43 -0
  27. package/lib/runtime-context.d.ts +29 -0
  28. package/lib/runtime-context.js +6 -0
  29. package/lib/schedule-types.d.ts +333 -0
  30. package/lib/schedule-types.js +4 -0
  31. package/lib/session-events.d.ts +194 -0
  32. package/lib/session-events.js +2 -0
  33. package/lib/sessions.d.ts +246 -0
  34. package/lib/sessions.js +2 -0
  35. package/lib/settings.d.ts +86 -0
  36. package/lib/settings.js +13 -0
  37. package/lib/storage.d.ts +144 -0
  38. package/lib/storage.js +62 -0
  39. package/lib/subagents.d.ts +57 -0
  40. package/lib/subagents.js +17 -0
  41. package/lib/subprocess.d.ts +97 -0
  42. package/lib/subprocess.js +8 -0
  43. package/lib/tools.d.ts +212 -0
  44. package/lib/tools.js +2 -0
  45. package/lib/web.d.ts +192 -0
  46. package/lib/web.js +53 -0
  47. package/package.json +1 -1
package/lib/porting.js CHANGED
@@ -1,55 +1,511 @@
1
1
  /**
2
- * 对照表:0.12 写法(0.12 插件契约)的每项服务、扩展点与常用函数在 SDK 2.0 里的对应(docs/rust-host/architecture.md
2
+ * 对照表:0.12 写法(0.12 插件契约)的每项服务、扩展点与常用函数在 SDK 2.x 里的对应(docs/rust-host/architecture.md
3
3
  * 「移植路径」)。插件契约文档里的对照表、codemod 的改写与插件运行时加载失败的提示都取自这里。
4
4
  *
5
- * 覆盖面由测试守住:0.12 契约的 17 项服务、现有 TS 插件与 0.12 模板用到的全部 0.12 导出、服务、成员与扩展点都要有一行
6
- * (tests/porting-table.test.ts);写着 SDK 对应名字的行,SDK 里要真有这个导出。
5
+ * 覆盖面由测试守住(tests/porting-table.test.ts):0.12 宿主的 255 项核心接口(tests/fixtures/dsh-core-surface.json,补齐的
6
+ * 方案与阶段见 docs/rust-host/plugin-parity.md)、0.12 契约的 17 项服务、现有 TS 插件与 0.12 模板用到的全部 0.12 导出、服务、
7
+ * 成员与扩展点都要有一行;写着 SDK 对应名字的行,SDK 里要真有这个导出。
8
+ *
9
+ * 0.12 是 dsh 0.2.1-alpha.2,表以它为准;也覆盖第三方插件实际依赖的 dsh 0.1.0-rc.7 到 0.2.2-rc.1(docs/rust-host/dsh-porting-plan.md
10
+ * 的 A5):形状与 0.12 不同的在说明里按版本写明(「dsh 0.2.2-rc.1 起…」),只在别的版本里有的服务也各有一行
11
+ * (tests/fixtures/dsh-services-versions.json)。
7
12
  *
8
13
  * 表里的 `@deepseek-ai/*` 是 0.12 插件里写的旧包名,仓库已不依赖这些包:留着是为了给按 0.12 写的第三方插件指出对应,
9
14
  * codemod 也要按它们认出要改写的引用。
10
15
  * @module @ftai/plugin-host-api/porting
11
16
  */
12
17
  const HOST = '@ftai/plugin-sdk/host';
18
+ /** TS 不能替换 Agent 驱动(plugin-parity.md 的决定)。 */
19
+ const NO_AGENT_FACTORY = 'TS 不能替换 Agent 驱动:建 agent 用 `ctx.agents.create`;要自写回路,用 `ctx.agents.create`、`ctx.llm.stream` 与 `ctx.tools.execute`';
20
+ const CONFIGURED_AGENTS = '不提供:声明式的 agent 列表是 0.12 改 `agent-loop` 这一行的配置,FtAi 不允许覆盖其他插件。要在启动时建或续 agent,在插件的 `apply` 里调 `ctx.agents.create`、`resume`,失败自己处理';
21
+ const AGENT_WRITE = '返回 Promise,加 `await`:要跨进程,错误交回调用方;子 agent 的会话一律拒绝';
22
+ const INBOX_READ = '读属性得到 Promise,加 `await`';
23
+ const INBOX_WRITE = '返回 Promise,加 `await`;子 agent 的会话一律拒绝';
24
+ const NO_SANDBOX = '插件不自己围沙箱:写二进制用 `ctx.fs.writeBytes`,宿主按这次工具调用所在会话的沙箱围住,越界时报 `FS_SANDBOX_DENIED`,说明就是给模型看的;工具要为写入申请提权(`sandbox_permissions`)时在定义里写 `sandboxEscalation: true`(见 `ctx.tools` 一行)';
25
+ const SANDBOX_POLICY = '只读:`await ctx.sandboxPolicy.resolve({ sessionId, execution })`(`session` 换成会话 id;`execution` 是进行中工具调用的句柄,同 `ctx.fs`,读这次调用定下的模式)、`overrideOf(sessionId)`、`defaultMode()`、`workspaceRoot()`,都是 Promise。不收调用方传入的模式(`mode` 报 `invalid_params`);写文件用 `ctx.fs.writeBytes`,跑命令用 `ctx.shell`,宿主围住';
26
+ const SCRIPT_RUNTIME = '阶段 4:脚本运行时(Code mode、`run_code`),单独立项';
27
+ const COMMAND_LINE = '外部进程按命令行拉起用 `ftai app --profile <名> -- <参数>`(0.12 的 `dsh --profile x <参数>`)';
28
+ const WEB_SERVER = '路由在插件进程里分派,对外是宿主协议的端口,只听本机回环;同 0.12,插件的路由不要求令牌。与 0.12 不同,宿主转发之前核对 Host 与 Origin(防 DNS 重绑定与跨站请求):Host 要是本机回环或用户在设置里加的可信 Host(「功能与插件」页,给经隧道收 webhook 之类),带 Origin 时要与 Host 相同,不对的答 403;不带 Origin 的照收(服务器发来的 webhook、浏览器的普通跳转)。应用的页面经主进程转发相对路径(`fetch(\'/my-plugin/x\')`),宿主加上 `x-ftai-web-client: app`;页面收不到插件设的 Cookie。`/`、`/index.html`、`/ws` 与 `/assets`、`/client` 下是应用自己的,注册时抛错。不压缩答复(0.12 默认也不压缩)';
29
+ const CONNECTION = '宿主一半:`/api` 下的精确路由(`fetch.register`)、放行(`requestRejection`、`admit`)与令牌换浏览器会话,关同 0.12(Host 是本机回环、不跨站、来源相同,再要已登录)。已登录指应用自己的页面(宿主加的 `x-ftai-web-client: app`)或换到的浏览器会话。0.12 界面的 RPC 通道(`rpc`)不提供';
30
+ /** 0.12 的数据目录根(`~/.dsh`)不给插件:插件只管自己的目录(SDK 2.2 的 `ctx.localInstall`)。 */
31
+ const NO_HARNESS_HOME = '宿主数据目录的根不给插件。插件自己的文件放 `ctx.localInstall.dataDir`(用户的数据,卸载时默认留下)或 `cacheDir`(能重新下载的内容,插件没在运行时宿主可能清空,卸载时删掉),都是同步读的绝对路径,用时自己建;小块数据用 `ctx.storageDomain`,配置用 `ctx.settings`,读会话用 `ctx.sessions`';
32
+ /** 0.12 的服务里不在补齐的 255 项之内、宿主也没有提供的(plugin-parity.md「发布前验收」)。 */
33
+ const UNSCHEDULED = '没有排期:不在补齐接口的 255 项之内,宿主没有提供';
34
+ /** 0.12 只在界面一侧的服务。 */
35
+ const CLIENT_SIDE = '没有排期:0.12 界面一侧的服务。插件界面一半用 `@ftai/plugin-sdk/app` 与 `/features`;插件后端给界面的接口写成 remote(插件契约「前后端通信」)';
36
+ /**
37
+ * 依赖这些服务的插件按「尚未提供」加载失败、写明服务名,不再一直等它出现。名单来自 tests/fixtures/dsh-services.json;
38
+ * 有替代做法的单独成行,写在「现有插件用到的其他服务」之后。
39
+ */
40
+ const UNSCHEDULED_HOST = [
41
+ 'agentPresets', 'agentTeams', 'authorization', 'browserUse', 'claudeCodeMods', 'computerUse', 'configEditor', 'cordisInspect',
42
+ 'credentialsController', 'deepseekAccount', 'deepseekLlmApiExtensions', 'directoryPicker', 'directoryPickerController',
43
+ 'dynamicCordisRunner', 'fileReferences', 'hmr', 'inspector', 'jobController', 'launchEnvironment', 'launcherSessionQueryPath', 'lsp',
44
+ 'messageFeedback', 'officeToPdf', 'otel', 'pluginManager', 'pluginPackages', 'profileContext', 'ptcRuntime', 'sessionController',
45
+ 'sessionFeedback', 'sessionFileReferences', 'sessionLogDownload', 'sessionReferenceResolver', 'sessionSkillCatalog', 'sessionTelemetry',
46
+ 'sessionTitle', 'settingsController', 'shellEnv', 'speechController', 'speechToText', 'spillStore', 'subagentModelSelection',
47
+ 'terminalController', 'terminals', 'tokenMeter', 'toolResultPruner', 'typertGateway', 'webTerminals', 'webhookRuntime',
48
+ 'workspaceChanges', 'workspaceController', 'workspaceFiles', 'workspaces',
49
+ // 0.12 里有、名单(从 alpha.1 的源码扫出)漏掉的
50
+ 'productTelemetry', 'ssh', 'timer', 'translator', 'worktrees',
51
+ ];
52
+ const UNSCHEDULED_CLIENT = [
53
+ 'chatFileMentions', 'clientModules', 'commandUi', 'configForms', 'conversation', 'documentPreviews', 'feedbackUi', 'fileUpload',
54
+ 'fileUploads', 'inputTriggers', 'layout', 'locale', 'modelDirectories', 'modules', 'pluginNavigation', 'pluginRegistryProbe',
55
+ 'productAnalytics', 'resources', 'settingsSchema', 'shortcuts', 'sidebarRight', 'sidebarRightTabs', 'slots', 'theme', 'uiConversation',
56
+ 'uiRenderer', 'uiSession', 'uiWorkspace', 'userQuestionPanels',
57
+ 'cotTranslation',
58
+ ];
59
+ /** 只在 dsh 的其他版本里有、0.12 没有的服务(A5 的版本比对,tests/fixtures/dsh-services-versions.json)。 */
60
+ const OTHER_VERSIONS = '没有排期:dsh 其他版本里的服务(0.12 没有),宿主没有提供';
61
+ const OTHER_VERSIONS_HOST = [
62
+ 'actionCards', 'apiProxy', 'codeRuntime', 'cuaAccess', 'e2b', 'forge', 'forgeSession', 'headlessStartup', 'invariants',
63
+ 'liveshareShares', 'pluginMarket', 'pluginRecommendations', 'remoteAccess', 'sessionLogDeepSeek', 'webApp',
64
+ ];
65
+ const OTHER_VERSIONS_CLIENT = [
66
+ 'appShell', 'contextMenus', 'conversationEvents', 'conversationViews', 'fileActions', 'fileDrag', 'forgePanel', 'pluginChanges',
67
+ 'settingsScope',
68
+ ];
69
+ /** dsh 0.1.5 及更早的设置接口:0.1.7 起换成 `configure`。 */
70
+ const SETTINGS_BEFORE_0_1_7 = 'dsh 0.1.5 及更早的写法(0.1.7 起换成 `configure`):配置写成插件的 `Config`,值是 `apply` 的第二个参数,要读当前值用 `ctx.settings.describe()`;设置页写在界面一半的 `settings`';
13
71
  export const PORTING_TABLE = [
14
- // ── 0.12 契约的 17 项服务 ──
15
- { legacy: 'ctx.tools', status: 'changed', sdk: 'ctx.tools', note: '`ctx.tools.register(defineTool({...}))` 照旧;工具定义只收 `name`、`description`、`parameters`、`output`、`execute`、`isConcurrencySafe`(只接受常量)、`needsApproval` 与 `sandboxEscalation`(新加:申请提权,见 `ctx.fs.sandboxMode` 一行),其余同步回调不再提供(见 `ToolDefinition` 一行)' },
16
- { legacy: 'ctx.tools.register', status: 'same', sdk: 'ctx.tools' },
72
+ // ── 工具 ──
73
+ { legacy: 'ctx.tools', status: 'changed', sdk: 'ctx.tools', note: '`ctx.tools.register(defineTool({...}))` 照旧;`get`、`schemas`、`executionMode` 跨进程后返回 Promise,`get` 只给 schema、不含执行体;工具定义的差别见 `ToolDefinition` 一行;`presentAs` 在阶段 4。dsh 0.2.2-rc.1 起服务改名 `ToolsService`,另有 `resolve`、`definitions`、`executable`、`setExecutor`、`checkGuards`,这里不提供' },
74
+ { legacy: 'ctx.tools.register', status: 'same', sdk: 'ctx.tools', note: '收 `defineTool` 的结果,或直接写 JSON Schema 的定义(`parameters` 根上 `type: \'object\'`,schema 来自外面时用,同 0.12)。重名时插件加载失败。dsh 0.2.2-rc.1 起的第二个参数 `{ when }`(按会话决定工具出不出现)不支持,传了就抛错;要按 agent 收起,在 `agent/created` 里调用 `agent.ctx.tools.restrict(filter)`' },
17
75
  { legacy: 'ctx.tools.restrict', status: 'changed', note: '只能按 agent 收起:在 `agent/created` 里调用 `agent.ctx.tools.restrict(filter)`,随 agent 结束撤销' },
18
- { legacy: 'ctx.llm', status: 'changed', sdk: 'ctx.llm', note: '模型路由改为 `ctx.llm.registerRoute(route, credentials)`(0.12 的 `registerAdapter`);直接调用模型只有 `stream`(没有 `generate`,输出用 `BlockAssembler` 拼)与 `resolveModelInfo`' },
19
- { legacy: 'ctx.llm.registerAdapter', status: 'changed', sdk: 'ctx.llm', note: '改为 `ctx.llm.registerRoute(route, credentials)`:一个 provider 与它的模型清单,每次请求经回调向插件取地址与凭据;清单变了就撤销旧的注册、再注册一次' },
20
- { legacy: 'ctx.llm.stream', status: 'changed', sdk: 'ctx.llm', note: '`GenerateOptions` 只收插件直接调用用得到的字段(见 `GenerateOptions` 一行);模型不收图时图片换成占位文本、请求照发,同 0.12;不重试,失败是最后一个 `finish` 块' },
21
- { legacy: 'ctx.llm.resolveModelInfo', status: 'same', sdk: 'ctx.llm', note: '没有这个 provider 报 `NO_ADAPTER`,没有这个模型报 `UNKNOWN_MODEL`(`LlmError`)' },
22
- { legacy: 'ctx.agents', status: 'changed', sdk: 'ctx.agents', note: '`get(id)`、`list()` 给出 agent 的句柄(同一个 id 总是同一个对象),保留 `agent.id`、`agent.session`、`agent.ctx`;`agent.inject()` 宿主尚未提供(线 A Loop)' },
23
- { legacy: 'ctx.agents.get', status: 'changed', sdk: 'ctx.agents', note: '参数是会话 id 字符串(不再有 `SessionId` 包装),返回句柄或 undefined' },
24
- { legacy: 'ctx.systemPrompt', status: 'changed', sdk: 'ctx.systemPrompt', note: '`section({ name, order, text })` 只收静态文本;函数形式的段落改为在 `agent/created` 里经 `agent.ctx.systemPrompt.section()` 按 agent 注册;`system-prompt/assemble` 不再提供' },
25
- { legacy: 'ctx.systemPrompt.section', status: 'changed', sdk: 'ctx.systemPrompt', note: '`text` 只能是字符串' },
26
- { legacy: 'ctx.systemPrompt.getSectionOrder', status: 'removed', note: '`order` 直接写数字,照 0.12 的 `SECTION_ORDERS`(如 `MCP_SERVERS` 是 3100)' },
27
- { legacy: 'ctx.commands', status: 'pending', note: '斜杠命令:宿主尚未提供,归属待定' },
28
- { legacy: 'ctx.skills', status: 'pending', note: '线 B 第 4 批(skills)' },
29
- { legacy: 'ctx.sessions', status: 'changed', note: '插件记录改用 SDK 的 `appendPluginRecord()`(异步);读写会话日志的其余方法不再提供;导出会话日志改用内部 SDK 的 `ctx.sessionLog.read(sessionId)`(只给一方插件)' },
30
- { legacy: 'ctx.sessionProjections', status: 'changed', sdk: 'ctx.sessionProjections', note: '`register()` 照旧(reducer 在插件进程里运行);`stateOf()` 改为异步,加 `await`' },
31
- { legacy: 'ctx.sessionProjections.register', status: 'same', sdk: 'ctx.sessionProjections' },
32
- { legacy: 'ctx.sessionProjections.stateOf', status: 'changed', sdk: 'ctx.sessionProjections', note: '返回 Promise:`await ctx.sessionProjections.stateOf(session, key)`,所在的监听者改成 async' },
33
- { legacy: 'ctx.fs', status: 'changed', sdk: 'ctx.fs', note: '宿主上的操作中途取消不了(`signal` 在调用前后各查一次);写二进制改用 `ctx.fs.writeBytes(target, bytes, { execution, expected })`,宿主在写之前跑 `fs/write-intent`;没有 `sandboxMode`' },
76
+ { legacy: 'ctx.tools.guard', status: 'changed', sdk: 'ctx.tools', todo: false, note: '排在全部 `tools/pre-execute` 与审批之后、工具体之前,只能拒绝。可以是异步的;抛错、超时(60 秒)或插件进程不在时当它没表态(0.12 按拒绝);要按拒绝写 `ctx.tools.guard(guard, { failClosed: true })`,这时进程重启、重新激活之前调用不派发' },
77
+ { legacy: 'ctx.tools.get', status: 'changed', sdk: 'ctx.tools', awaited: 'call', note: '返回 Promise,加 `await`;只有 `name`、`description`、`parameters`,不含执行体与回调,也没有 `timeoutMs`(宿主按工具声明的时限自己管超时,不用再包一层)。每次是新对象,不能用 `===` 比较。dsh 0.2.2-rc.1 起的第三个参数 `toolSet` 不支持,传了不生效' },
78
+ { legacy: 'ctx.tools.schemas', status: 'changed', sdk: 'ctx.tools', awaited: 'call', note: '返回 Promise,加 `await`;不给 `scope` 时是全局注册的,不给 `deferLoading`。dsh 0.2.2-rc.1 起的第二个参数 `toolSet` 不支持,传了不生效' },
79
+ { legacy: 'ctx.tools.executionMode', status: 'changed', sdk: 'ctx.tools', awaited: 'call', note: '返回 Promise,加 `await`;判定函数超时(5 秒)、抛错或不是 `true` 都是 `exclusive`' },
80
+ { legacy: 'ctx.tools.execute', status: 'changed', sdk: 'ctx.tools', note: '走模型发起时的同一条路(`tools/pre-execute`、审批、`guard`、沙箱、`tools/execute`、`tools/post-execute`),同 0.12 不写 tool/call 与 tool/result。`agent` 必填;要审批的调用只能在进行中的一轮里;核心工具的结果没有 `value`;没有这个 agent 或会话已归档时 Promise 拒绝。dsh 0.2.2-rc.1 起改成一次执行一批(`execute({ calls, signal, agent })`,结果是 `{ results, additionalContexts, concluded }`);这里照 0.12 一次执行一个调用,逐个调用后自己拼结果' },
81
+ { legacy: 'ctx.tools.presentAs', status: 'pending', note: SCRIPT_RUNTIME },
82
+ { legacy: 'tools/pre-execute', status: 'changed', sdk: 'tools/pre-execute', note: '`exec` 是工具调用的句柄(同一次调用总是同一个对象),`exec.arguments` 照 0.12 是解析后的 JSON;结论的四种 `kind` 写法照旧。`allow` 同 0.12 跳过工具本身要求的审批:不出卡,记为这个插件代答;但越不过用户的设置,审批策略 never 时照样拒绝、「替我审批」时照样交审查者,命令规则里要询问的命令与危险命令照样问。`ask` 可以带 `displayReason`(`{ en, zh }`,只给界面、不落盘,没有 `en` 时不用)。抛错、超时或插件进程不在时当它没表态(0.12 按拒绝);注册时写 `{ failClosed: true }` 的按拒绝,进程重启、重新激活之前调用不派发' },
83
+ { legacy: 'tools/post-execute', status: 'changed', sdk: 'tools/post-execute', note: '写法照旧。换 `value` 只对 TS 插件的工具有效,核心工具没有 `value`;`additionalContexts` 的来源同 `deferContext`。不调用 `next` 时宿主补跑下游,下游拦下则拦下。超时(60 秒)、抛错或插件进程不在时当它没表态,结果照下游的;要拦住内容的监听者写 `{ failClosed: true }`,这时结果换成固定的失败文本,不回退到原文;这一轮已取消时不再等,换成取消的结果' },
84
+ { legacy: 'tools/execute', status: 'changed', sdk: 'tools/execute', note: '写法照旧:`next()` 可以再调用一次重试(前一次结束之后),可以换 `exec.signal`(只在监听者运行期间),改不了参数与调用身份。不设超时;监听者失败时当它没表态:没调用过 `next()` 就照常执行工具,拿到过结果就用它,调用了还没拿到(插件进程不在时工具随之停下)与声明了 `failClosed` 的这次调用按失败收。核心工具体经宿主被丢掉,不是收到 signal;核心工具的结果没有 `value`,自己写成功结果时给 `content`' },
85
+ { legacy: 'tools/result', status: 'changed', sdk: 'tools/result', todo: false, note: '工具结果定下时通知(按模型给的顺序,紧接着记成 tool/result),不等答复;核心工具的结果没有 `value`' },
86
+ { legacy: 'tools/change', status: 'same', sdk: 'tools/change', note: '工具注册或收起变了时通知,不按 agent 过滤;通知另起任务发出,要读最新的工具重新调用 `await ctx.tools.schemas()`' },
87
+ { legacy: 'tools/ptc-dispatch-log', status: 'pending', note: SCRIPT_RUNTIME },
88
+ // ── 模型 ──
89
+ { legacy: 'ctx.llm', status: 'changed', sdk: 'ctx.llm', note: '接口同名,形状变化见各自一行:同步读取变成 Promise;同步查询(重试策略、图片定价)注册时以数据给出;适配器只有流式实现;路由的 key 与请求头不经过任何接口' },
90
+ { legacy: 'ctx.llm.registerAdapter', status: 'changed', sdk: 'ctx.llm', note: '两种写法。协议层由宿主负责:`ctx.llm.registerRoute(route, credentials)`,每次请求经回调向插件取地址与凭据。插件自己发 HTTP:`ctx.llm.registerAdapter(routes, { stream(options) })`,逐块给出 v4 的 `StreamChunk`,宿主核对形状,插件崩溃或超时(300 秒没有产出)时这次请求以 `error` 的 `finish` 结束。第一个参数是路由清单(`RouteDeclaration`),不是 provider 名;`providerInfo`、`listModels`、`resolveModel`、`providerRetryPolicy`、`imageRequestPricing` 不再是方法,写进清单。`handle.replace` 返回 Promise,校验错误(0.12 同步抛出)从 `handle.ready` 与它的 Promise 报' },
91
+ { legacy: 'ctx.llm.stream', status: 'changed', sdk: 'ctx.llm', todo: false, note: '`tools`、`temperature`、`stop`、`purpose` 同 0.12;没有 `toolHistory`(路由都按完整声明发)。Responses 协议没有 `stop` 字段,宿主在流里截断并断开上游,上游已生成的 token 照算。模型不收图时图片换成占位文本、请求照发,同 0.12;不重试,失败是最后一个 `finish` 块;`finish` 带 `replayState`,经 `BlockAssembler.message()` 放回下一次请求' },
92
+ { legacy: 'ctx.llm.resolveModelInfo', status: 'changed', sdk: 'ctx.llm', todo: false, note: '没有这个 provider 报 `NO_ADAPTER`,没有这个模型报 `UNKNOWN_MODEL`(`LlmError`);`reasoning.efforts` 的 `name` 就是档位 id(宿主不写自然语言名字,由界面翻译);`description` 只有路由声明了才有;`systemPromptUpdate`、`toolUpdate` 总是没有' },
93
+ { legacy: 'ctx.llm.listProviders', status: 'changed', sdk: 'ctx.llm', awaited: 'call', note: '返回 Promise,加 `await`。后台服务刚启动、账号的模型清单还在第一次加载时先等它,最多 10 秒,外部应用一拉起就列也拿得到完整的目录' },
94
+ { legacy: 'ctx.llm.listModels', status: 'same', sdk: 'ctx.llm', note: '藏起来的模型不列;每一项还带 `resolveModelInfo` 的字段;路由还没有、第一次加载还没完时先等,同 `listProviders`' },
95
+ { legacy: 'ctx.llm.registerConfigurableProviders', status: 'changed', sdk: 'ctx.llm', note: '空列表同步报 `INVALID_DIRECTORY`;其余校验错误(`DUPLICATE_DIRECTORY`)要跨进程:从 `handle.ready` 报;`handle.replace` 返回 Promise。目录里只有插件声明的,核心的第三方提供方不在里面' },
96
+ { legacy: 'ctx.llm.listConfigurableProviders', status: 'changed', sdk: 'ctx.llm', awaited: 'call', note: '返回 Promise,加 `await`;只有插件声明的条目' },
97
+ { legacy: 'ctx.llm.registerModelDiscovery', status: 'same', sdk: 'ctx.llm', note: '重复注册的 `DUPLICATE_DISCOVERY` 只进日志(0.12 同步抛出)' },
98
+ { legacy: 'ctx.llm.discoverModels', status: 'same', sdk: 'ctx.llm', note: '发现实现出错时报 `DISCOVERY_FAILED`,60 秒没有结果报 `TIMEOUT`' },
99
+ { legacy: 'ctx.llm.remoteDiscoverModels', status: 'changed', sdk: 'ctx.llm', todo: false, note: '宿主协议上没有 `llm` 命名空间:界面要用时由插件自己的 `@Remote` 方法转一道;失败报 `RemoteError`(`llm/model-discovery-rejected`)' },
100
+ { legacy: 'ctx.llm.providerRetryPolicy', status: 'changed', sdk: 'ctx.llm', awaited: 'call', note: '返回 Promise,加 `await`。路由在注册时以数据给出(`retryPolicy`),内置重试照它执行;只有 `normal` 一种:`always` 写不进核对过的会话写法,注册时拒绝' },
101
+ { legacy: 'ctx.llm.imageRequestPricing', status: 'changed', sdk: 'ctx.llm', awaited: 'call', note: '返回 Promise,加 `await`;结果是路由注册时声明的数据(`modelOptions[id].imagePricing`:`baseTokens`、`pixelsPerToken`、`maxTokens`),没有 `priceImages` 函数,上下文计量按它算' },
102
+ { legacy: 'ctx.llm.fileRequestText', status: 'changed', sdk: 'ctx.llm', awaited: 'call', note: '返回 Promise,加 `await`' },
103
+ { legacy: 'ctx.llm.resolveCallConfig', status: 'same', sdk: 'ctx.llm', note: '与 `stream` 共用同一份规则;0.12 的 `adapter` 自定义的解析不再有' },
104
+ { legacy: 'ctx.llm.prepareCall', status: 'same', sdk: 'ctx.llm', note: '`configure` 照旧在插件进程里同步调用。句柄在宿主里是 id,凭据只在派发时向注册方取,注册方断开时这次调用按缺凭据结束。没派发的句柄最多留 256 个,超出时最早的失效(`INVALID_PREPARED_CALL`)' },
105
+ { legacy: 'ctx.llm.typertRemote', status: 'removed', note: '0.12 内部的网关绑定,插件用不到;调用模型用 `ctx.llm.stream`' },
106
+ { legacy: 'llm/stream', status: 'changed', sdk: 'llm/stream', todo: false, note: '同 0.12 写:`(options, next) => AsyncIterable<StreamChunk>`,写进会话的是改写后的结果。作用于 Agent 回路(含子 agent)与插件的 `ctx.llm.stream`,Guardian、标题、压缩不经过它。`next()` 每次调用发起一次下游请求,都从后面的第一个监听者开始(0.12 第二次调用会跳过后面的监听者);`options` 冻结,改不了请求。监听者抛错、形状不对、60 秒没有产出也没有在等下游、或进程不在时,这次请求以 `error` 的 `finish` 结束' },
107
+ { legacy: 'llm/adapters-updated', status: 'same', sdk: 'llm/adapters-updated', note: '模型清单变化也发;一批变化可能合成一次' },
108
+ // ── 驱动 Agent ──
109
+ { legacy: 'ctx.agents', status: 'changed', sdk: 'ctx.agents', note: '`create`、`resume`、`get`、`list`、`roots`、`isOwnedBy` 与发起者四个方法都有,见各自一行;`setFactory`、`register`、`enter`、`announce` 不提供。`agent` 是跨进程的句柄(同一个 id 总是同一个对象),读状态与发消息都异步,codemod 对直接写的调用、经一层别名或解构的调用自动加 `await`;把 `ctx.agents` 传走或存进字段的地方认不出来,在那里写明「此处未加 await」。dsh 0.2.2-rc.1 起的 `turnBoundaryOf(session)` 不提供:用 `await ctx.sessionProjections.stateOf(session, \'turnBoundary\')`' },
110
+ { legacy: 'ctx.agents.create', status: 'changed', sdk: 'ctx.agents', note: '结果是 `OwnedAgent`(0.12 的 `AgentHandle`,同形 `{ agent, dispose }`);`meta` 只收 `cwd`,`seed`、`inheritedEventCount` 报错;已有的会话 id 报 `agent/session-exists`;没给模型时用新对话的默认模型;插件建的是普通会话,权限是新会话的默认(`workspace-write`);要审批的动作没有界面应答时立即 `unavailable`(拒绝):外部应用用 `ftai app --preset` 指定预设,或插件监听 `approval/request` 代答、用 `ctx.permissionPresets.set` 切预设(切到完全访问要用户先在设置里允许)' },
111
+ { legacy: 'ctx.agents.resume', status: 'changed', sdk: 'ctx.agents', note: '结果是 `OwnedAgent`;不存在的会话 id 报 `agent/session-not-found`;可以接手用户正开着的会话,`dispose()` 会停下这个会话在跑的一轮,插件自己判断要不要调用。对已在内存的 agent 不拒绝(0.12 拒绝):续失败时这次 `setup` 的注册不撤销,随 agent 卸下一起撤' },
112
+ { legacy: 'ctx.agents.get', status: 'changed', sdk: 'ctx.agents', note: '同步,只认本进程见过的 agent(要全部活着的用 `await ctx.agents.list()`);参数是会话 id 字符串,`SessionId(...)` 包装由 codemod 去掉' },
113
+ { legacy: 'ctx.agents.list', status: 'changed', sdk: 'ctx.agents', awaited: 'call', note: '返回 Promise,加 `await`:宿主内存里全部的 agent,按建立的先后' },
114
+ { legacy: 'ctx.agents.roots', status: 'changed', sdk: 'ctx.agents', awaited: 'call', note: '返回 Promise,加 `await`:没有持有者的 agent' },
115
+ { legacy: 'ctx.agents.isOwnedBy', status: 'changed', sdk: 'ctx.agents', awaited: 'call', note: '返回 Promise,加 `await`:`owner` 是不是这个 agent 的直接持有者' },
116
+ { legacy: 'ctx.agents.currentInitiator', status: 'same', sdk: 'ctx.agents', note: '用 `AsyncLocalStorage` 实现,只在插件进程内有效:工具执行与带 agent 的扩展点监听者里是那个 agent,`session/event` 里是这个会话的 agent' },
117
+ { legacy: 'ctx.agents.requireInitiator', status: 'same', sdk: 'ctx.agents', note: '同 `currentInitiator`,没有发起者时抛错' },
118
+ { legacy: 'ctx.agents.withInitiator', status: 'same', sdk: 'ctx.agents' },
119
+ { legacy: 'ctx.agents.withoutInitiator', status: 'same', sdk: 'ctx.agents' },
120
+ { legacy: 'ctx.agents.setFactory', status: 'removed', note: NO_AGENT_FACTORY },
121
+ { legacy: 'ctx.agents.register', status: 'removed', note: NO_AGENT_FACTORY },
122
+ { legacy: 'ctx.agents.enter', status: 'removed', note: NO_AGENT_FACTORY },
123
+ { legacy: 'ctx.agents.announce', status: 'removed', note: NO_AGENT_FACTORY },
124
+ { legacy: 'ctx.agentLoop', status: 'removed', note: NO_AGENT_FACTORY },
125
+ { legacy: 'ctx.configuredAgentIdentities', status: 'removed', note: CONFIGURED_AGENTS },
126
+ { legacy: 'agent-loop/config-start-failed', status: 'removed', note: CONFIGURED_AGENTS },
127
+ { legacy: 'ctx.agentDefaultModel', status: 'changed', sdk: 'ctx.agentDefaultModel', note: '只有 `currentSelection` 与 `saveSelection`,都是异步的;对第三方插件开放,`saveSelection` 能改掉用户新对话的默认模型' },
128
+ { legacy: 'ctx.agentDefaultModel.currentSelection', status: 'changed', sdk: 'ctx.agentDefaultModel', awaited: 'call', note: '返回 Promise,加 `await`;没有默认模型时为 null' },
129
+ { legacy: 'ctx.agentDefaultModel.saveSelection', status: 'same', sdk: 'ctx.agentDefaultModel' },
130
+ { legacy: '@deepseek-ai/dsh-agent#Agent', status: 'changed', sdk: `${HOST}#Agent`, todo: false, note: 'agent 的句柄(SDK 的 `AgentHandle`):读状态、发消息与改收件箱都异步,codemod 自动加 `await`;其余见 `Agent.*` 各行' },
131
+ { legacy: '@deepseek-ai/dsh-agent#Agent.id', status: 'same', sdk: `${HOST}#Agent`, note: '会话 id 字符串,不是品牌类型' },
132
+ { legacy: '@deepseek-ai/dsh-agent#Agent.options', status: 'changed', sdk: `${HOST}#Agent`, awaited: 'read', note: '读属性得到 Promise,加 `await`:这个 agent 此刻的请求配置' },
133
+ { legacy: '@deepseek-ai/dsh-agent#Agent.status', status: 'changed', sdk: `${HOST}#Agent`, awaited: 'read', note: '读属性得到 Promise,加 `await`' },
134
+ { legacy: '@deepseek-ai/dsh-agent#Agent.session', status: 'changed', sdk: `${HOST}#SessionHandle`, todo: false, note: '会话的句柄:`id`、`header.cwd` 同步可读,其余读法见 `Session.*` 各行' },
135
+ { legacy: '@deepseek-ai/dsh-agent#Agent.inbox', status: 'changed', sdk: `${HOST}#Inbox`, todo: false, note: '读与改都异步,见 `Inbox.*` 各行' },
136
+ { legacy: '@deepseek-ai/dsh-agent#Agent.ctx', status: 'same', sdk: `${HOST}#Agent`, note: '真的 `Context`:`agent.ctx.on(...)` 只收到这个 agent 的事件,`effect`、`tools`、`systemPrompt`、`agents` 都可用,随 agent 从宿主内存卸下(`agent/disposed`)撤销' },
137
+ { legacy: '@deepseek-ai/dsh-agent#Agent.cancel', status: 'changed', sdk: `${HOST}#Agent`, awaited: 'call', note: '返回 Promise,加 `await`;原因只收 `user`、`parent`、`hook`,0.12 的 `disposed` 不再有' },
138
+ { legacy: '@deepseek-ai/dsh-agent#Agent.whenIdle', status: 'same', sdk: `${HOST}#Agent` },
139
+ { legacy: '@deepseek-ai/dsh-agent#Agent.runMaintenance', status: 'same', sdk: `${HOST}#Agent`, note: '任务在插件进程里跑,占住空闲的 agent;不空闲时报错,`signal` 随 `agent.cancel` 触发' },
140
+ { legacy: '@deepseek-ai/dsh-agent#Agent.send', status: 'changed', sdk: `${HOST}#Agent`, awaited: 'call', note: AGENT_WRITE },
141
+ { legacy: '@deepseek-ai/dsh-agent#Agent.followup', status: 'changed', sdk: `${HOST}#Agent`, awaited: 'call', note: AGENT_WRITE },
142
+ { legacy: '@deepseek-ai/dsh-agent#Agent.steer', status: 'changed', sdk: `${HOST}#Agent`, awaited: 'call', note: AGENT_WRITE },
143
+ { legacy: '@deepseek-ai/dsh-agent#Agent.inject', status: 'changed', sdk: `${HOST}#Agent`, awaited: 'call', note: AGENT_WRITE },
144
+ { legacy: '@deepseek-ai/dsh-agent#Inbox', status: 'changed', sdk: `${HOST}#Inbox`, todo: false, note: '读与改都要跨进程,都是异步的,codemod 自动加 `await`' },
145
+ { legacy: '@deepseek-ai/dsh-agent#Inbox.nextTurn', status: 'changed', sdk: `${HOST}#Inbox`, awaited: 'read', note: INBOX_READ },
146
+ { legacy: '@deepseek-ai/dsh-agent#Inbox.nextStep', status: 'changed', sdk: `${HOST}#Inbox`, awaited: 'read', note: INBOX_READ },
147
+ { legacy: '@deepseek-ai/dsh-agent#Inbox.clear', status: 'changed', sdk: `${HOST}#Inbox`, awaited: 'call', note: INBOX_WRITE },
148
+ { legacy: '@deepseek-ai/dsh-agent#Inbox.append', status: 'changed', sdk: `${HOST}#Inbox`, awaited: 'call', note: INBOX_WRITE },
149
+ { legacy: '@deepseek-ai/dsh-agent#Inbox.prepend', status: 'changed', sdk: `${HOST}#Inbox`, awaited: 'call', note: INBOX_WRITE },
150
+ { legacy: '@deepseek-ai/dsh-agent#Inbox.replace', status: 'changed', sdk: `${HOST}#Inbox`, awaited: 'call', note: INBOX_WRITE },
151
+ { legacy: '@deepseek-ai/dsh-agent#Inbox.remove', status: 'changed', sdk: `${HOST}#Inbox`, awaited: 'call', note: INBOX_WRITE },
152
+ { legacy: '@deepseek-ai/dsh-agent#Inbox.splice', status: 'changed', sdk: `${HOST}#Inbox`, awaited: 'call', note: INBOX_WRITE },
153
+ { legacy: '@deepseek-ai/dsh-agent#AgentHandle', status: 'changed', sdk: `${HOST}#OwnedAgent`, todo: false, note: '改名 `OwnedAgent`,同形 `{ agent, dispose }`,codemod 连引用一起改;SDK 的 `AgentHandle` 已经指 agent 句柄(0.12 的 `Agent`)' },
154
+ { legacy: '@deepseek-ai/dsh-agent#CreateAgentOptions', status: 'changed', sdk: `${HOST}#CreateAgentOptions`, todo: false, note: '`meta` 只收 `cwd`,没有 `seed`、`inheritedEventCount`' },
155
+ { legacy: '@deepseek-ai/dsh-agent#ResumeAgentOptions', status: 'same', sdk: `${HOST}#ResumeAgentOptions` },
156
+ { legacy: '@deepseek-ai/dsh-agent#AgentSetup', status: 'same', sdk: `${HOST}#AgentSetup`, note: 'agent 发布之前往它的上下文里注册,只做组合,不驱动它' },
157
+ { legacy: '@deepseek-ai/dsh-agent#AgentOptions', status: 'changed', sdk: `${HOST}#AgentOptions`, todo: false, note: '只有 `provider`、`model`、`reasoningEffort`、`maxTokens`' },
158
+ { legacy: '@deepseek-ai/dsh-agent#AgentStatus', status: 'same', sdk: `${HOST}#AgentStatus` },
159
+ { legacy: '@deepseek-ai/dsh-agent#InboxTarget', status: 'same', sdk: `${HOST}#InboxTarget` },
160
+ { legacy: '@deepseek-ai/dsh-agent#CancelOptions', status: 'same', sdk: `${HOST}#CancelOptions` },
161
+ { legacy: '@deepseek-ai/dsh-agent#PreStepDecision', status: 'changed', sdk: `${HOST}#PreStepDecision`, todo: false, note: '没有 `startsRequestSeries`:只影响提示缓存的分段,宿主自己判断' },
162
+ { legacy: '@deepseek-ai/dsh-agent#RequestErrorAction', status: 'changed', sdk: `${HOST}#RequestErrorAction`, todo: false, note: '只有 `{ kind: \'retry\' }`,不含 undefined:监听者的返回类型写成 `RequestErrorAction | undefined`' },
163
+ { legacy: '@deepseek-ai/dsh-agent#AssistantStreamFrame', status: 'changed', sdk: `${HOST}#StreamFrame`, todo: false, note: '改名 `StreamFrame`,codemod 连引用一起改;同样是 `start`、`chunk`、`end` 三种帧,`chunk` 帧另带 `turn`、`step`' },
164
+ { legacy: '@deepseek-ai/dsh-session/types#AgentCancelCause', status: 'changed', sdk: `${HOST}#AgentCancelCause`, todo: false, note: '只有 `user`、`parent`、`hook`' },
165
+ { legacy: '@deepseek-ai/dsh-llm#UserMessage', status: 'same', sdk: `${HOST}#UserMessage` },
166
+ { legacy: '@deepseek-ai/dsh-llm#createUserMessage', status: 'same', sdk: `${HOST}#createUserMessage`, note: '同 0.12:分配 id 并冻结,`source.kind` 写消息的来源' },
167
+ { legacy: '@deepseek-ai/dsh-llm#LlmCallConfig', status: 'same', sdk: `${HOST}#LlmCallConfig`, note: '作为 `agent/request` 的结论时只认 `provider`、`model`、`reasoningEffort`、`maxTokens`' },
168
+ { legacy: '@deepseek-ai/dsh-llm#LlmCallControls', status: 'same', sdk: `${HOST}#LlmCallControls` },
169
+ { legacy: '@deepseek-ai/dsh-llm#ConfigureCall', status: 'same', sdk: `${HOST}#ConfigureCall` },
170
+ { legacy: '@deepseek-ai/dsh-llm#callConfigEquals', status: 'same', sdk: `${HOST}#callConfigEquals` },
171
+ { legacy: '@deepseek-ai/dsh-llm#isAgentLoopRequest', status: 'same', sdk: `${HOST}#isAgentLoopRequest`, note: '宿主在 `options.agentLoop` 上标明' },
172
+ { legacy: '@deepseek-ai/dsh-llm#markAgentLoopRequest', status: 'removed', note: 'Agent 回路由宿主驱动,请求由宿主标明;插件用 `isAgentLoopRequest` 读' },
173
+ { legacy: '@deepseek-ai/dsh-llm#LlmAdapter', status: 'changed', sdk: `${HOST}#LlmAdapter`, note: '接口,不是要继承的类:只有 `stream(options)`,路由清单与重试策略、图片定价在 `registerAdapter` 时以数据给出,见 `ctx.llm.registerAdapter` 一行' },
174
+ { legacy: '@deepseek-ai/dsh-llm#AdapterRegistrationHandle', status: 'changed', sdk: `${HOST}#AdapterRegistrationHandle`, note: '`replace` 收路由清单、返回 Promise;校验错误从 `ready` 与它的 Promise 报' },
175
+ { legacy: '@deepseek-ai/dsh-llm#DirectoryRegistrationHandle', status: 'changed', sdk: `${HOST}#DirectoryRegistrationHandle`, note: '`replace` 返回 Promise;校验错误从 `ready` 与它的 Promise 报' },
176
+ { legacy: '@deepseek-ai/dsh-llm#PreparedLlmCall', status: 'same', sdk: `${HOST}#PreparedLlmCall` },
177
+ { legacy: '@deepseek-ai/dsh-llm#ReplayEnvelope', status: 'same', sdk: `${HOST}#ReplayEnvelope` },
178
+ { legacy: '@deepseek-ai/dsh-llm#LlmProviderInfo', status: 'same', sdk: `${HOST}#LlmProviderInfo` },
179
+ { legacy: '@deepseek-ai/dsh-llm#LlmConfigurableProvider', status: 'same', sdk: `${HOST}#LlmConfigurableProvider` },
180
+ { legacy: '@deepseek-ai/dsh-llm#LlmModelDiscoveryRequest', status: 'same', sdk: `${HOST}#LlmModelDiscoveryRequest` },
181
+ { legacy: '@deepseek-ai/dsh-llm#LlmDiscoveredModel', status: 'same', sdk: `${HOST}#LlmDiscoveredModel` },
182
+ { legacy: '@deepseek-ai/dsh-llm#RetryPolicyConfig', status: 'changed', sdk: `${HOST}#RetryPolicyConfig`, note: '只有 `normal`:`always` 写不进核对过的会话写法' },
183
+ { legacy: '@deepseek-ai/dsh-llm#ResolvedRetryPolicy', status: 'changed', sdk: `${HOST}#ResolvedRetryPolicy`, note: '只有 `normal`' },
184
+ { legacy: '@deepseek-ai/dsh-llm#LlmImageRequestPricing', status: 'changed', sdk: `${HOST}#LlmImageRequestPricing`, note: '数据(`baseTokens`、`pixelsPerToken`、`maxTokens`),没有 `priceImages` 函数' },
185
+ { legacy: '@deepseek-ai/dsh-llm#ToolCallId', status: 'same', sdk: `${HOST}#ToolCallId`, brand: true, note: '就是字符串:`ToolCallId(...)` 包装由 codemod 去掉' },
186
+ { legacy: '@deepseek-ai/dsh-llm#MessageId', status: 'same', sdk: `${HOST}#MessageId`, brand: true, note: '就是字符串:`MessageId(...)` 包装由 codemod 去掉' },
187
+ { legacy: 'agent/created', status: 'changed', sdk: 'agent/created', todo: false, note: '载荷是 `{ agent, source, signal }`,`agent` 是句柄,按 agent 的注册写在 `agent.ctx` 上;`source` 只有 `startup`、`resume`(压缩在原 agent 上替换历史,不建新 agent)。dsh 0.2 之前的载荷只有 `agent`,照那样写的监听者不用改' },
188
+ { legacy: 'agent/session-start', status: 'removed', note: 'dsh 0.1.x 的写法,0.2 起并进 `agent/created`:改听 `agent/created`,看载荷的 `source`(`startup`、`resume`)' },
189
+ { legacy: 'ctx.agent', status: 'removed', note: 'dsh 0.1.x 在 agent 作用域上的当前 agent:改用 `agent/created` 载荷里的 `agent`,它的作用域是 `agent.ctx`' },
190
+ { legacy: 'agent/disposed', status: 'same', sdk: 'agent/disposed', note: 'agent 从宿主内存卸下;再用到这个会话时再发一次 `agent/created`' },
191
+ { legacy: 'agent/status', status: 'same', sdk: 'agent/status' },
192
+ { legacy: 'agent/error', status: 'changed', sdk: 'agent/error', todo: false, note: '`error` 是 `{ message, code }`:错误来自宿主,没有 JS 的原对象' },
193
+ { legacy: 'agent/inbox/inserted', status: 'same', sdk: 'agent/inbox/inserted', note: '由落盘的会话事件派生,异步送达' },
194
+ { legacy: 'agent/inbox/claimed', status: 'same', sdk: 'agent/inbox/claimed', note: '由落盘的会话事件派生,异步送达' },
195
+ { legacy: 'agent/inbox/discarded', status: 'same', sdk: 'agent/inbox/discarded', note: '由落盘的会话事件派生,异步送达' },
196
+ { legacy: 'agent/pre-step', status: 'changed', sdk: 'agent/pre-step', todo: false, note: '结论没有 `startsRequestSeries`;不调用 `next()` 时宿主补跑下游,下游否决则否决,不能绕过归档门禁等核心判定;消息形状不对、超时(60 秒)或插件进程不在时当它没表态;声明了 `failClosed` 的否决,这一轮以 `blocked` 结束。dsh 0.2.2-rc.1 起载荷带 `modelSelection`,这里没有:要这一步的模型,监听 `agent/request`,`next()` 的结果就是这一步的 provider、model 与档位' },
197
+ { legacy: 'agent/request', status: 'changed', sdk: 'agent/request', note: '结论只认 `provider`、`model`、`reasoningEffort`、`maxTokens`,Agent 的请求不带 `temperature`、`stop`;换到没注册的路由、超时或插件进程不在时这一轮以错误结束' },
198
+ { legacy: 'agent/request-error', status: 'changed', sdk: 'agent/request-error', note: '只能增加重试,不能取消内置重试:返回 `{ kind: \'retry\' }` 立即再请求一次,不计入内置重试的次数,退避由监听者自己等,没有次数上限;超时或插件进程不在时按不重试,交回内置逻辑' },
199
+ { legacy: 'agent/assistant-stream', status: 'changed', sdk: 'agent/assistant-stream', todo: false, note: '载荷是 `{ agent, frame }`;`frame` 有 `start`、`chunk`、`end` 三种,`chunk` 帧的 `chunk` 是会话格式 v4 的 `StreamChunk`,另带 `turn`、`step`' },
200
+ { legacy: 'agent/turn-stopping', status: 'same', sdk: 'agent/turn-stopping', note: '每个监听者最多等 30 秒;失败不影响这一轮结束,只记日志' },
201
+ // ── 提示词 ──
202
+ { legacy: 'ctx.systemPrompt', status: 'changed', sdk: 'ctx.systemPrompt', note: '名字与写法照 0.12。组装在宿主上:函数形式的取值在每一步组装之前跨进程取好,可以返回 Promise,失败或超时(30 秒)时这一轮以错误结束;`{{变量}}` 只在写了 `interpolate: true` 的段里替换;运行环境段不写 `required` 时不可收起。codemod 给 `section`、`context` 的注册补上 0.12 的默认值(见这两行)' },
203
+ { legacy: 'ctx.systemPrompt.section', status: 'changed', sdk: 'ctx.systemPrompt', note: '`text` 可以是字符串或函数。`{{变量}}` 只在写了 `interpolate: true` 的段里替换(0.12 不写就替换):codemod 给没写这一项的段补上 `interpolate: true`,同 0.12;参数不是对象字面量或带展开时插 TODO,要手工补。`order` 要是整数;重名时插件加载失败(0.12 当场抛错;激活之后才注册的,注册被拒但不算加载失败)' },
204
+ { legacy: 'ctx.systemPrompt.getSectionOrder', status: 'same', sdk: 'ctx.systemPrompt' },
205
+ { legacy: 'ctx.systemPrompt.getContextOrder', status: 'same', sdk: 'ctx.systemPrompt' },
206
+ { legacy: 'ctx.systemPrompt.context', status: 'changed', sdk: 'ctx.systemPrompt', note: '不写 `required` 时不可收起(0.12 不写就能收起),写 `required: false` 才是可选的;`{{变量}}` 只在写了 `interpolate: true` 的段里替换。codemod 给没写的补上 `interpolate: true` 与 `required: false`,同 0.12;参数不是对象字面量或带展开时插 TODO,要手工补。沙箱与审批说明的名字保留给宿主' },
207
+ { legacy: 'ctx.systemPrompt.suppressRuntimeContext', status: 'changed', sdk: 'ctx.systemPrompt', todo: false, note: '只收起写了 `required: false` 的段与宿主标为可选的段(记忆、子 agent 委派);工作目录、沙箱与审批的说明总在' },
208
+ { legacy: 'ctx.systemPrompt.tools', status: 'changed', sdk: 'ctx.systemPrompt', note: '给出的名字必须是这个 agent 看得到的工具(`ctx.tools.register` 注册的、没被收起的),否则这一轮以错误结束(0.12 到调用时才报 `UNKNOWN_TOOL`);同名不去重(同 0.12),要改工具说明用 `system-prompt/assemble`' },
209
+ { legacy: 'ctx.systemPrompt.variable', status: 'same', sdk: 'ctx.systemPrompt', note: '取值可以返回 Promise;取值失败或超时时这一轮以错误结束。`provider`、`model` 由宿主注册' },
210
+ { legacy: 'ctx.systemPrompt.refreshContext', status: 'changed', sdk: 'ctx.systemPrompt', awaited: 'call', note: '返回 Promise,加 `await`:要跨进程' },
211
+ { legacy: 'ctx.systemPrompt.assemble', status: 'changed', sdk: 'ctx.systemPrompt', todo: false, note: '`context` 只认 `scope`、`signal`,插件自己加的字段不跨进程;结果经过宿主的恢复与核对,不写会话' },
212
+ { legacy: 'system-prompt/assemble', status: 'changed', sdk: 'system-prompt/assemble', note: '载荷是 JSON,`this` 上没有服务对象;可以改身份段。之后宿主恢复完整段;运行环境段按注册的取值刷新(改文字不生效),只有瀑布加上的段保留,去掉的不可收起的段补回(沙箱与审批的说明总在);工具只认这个 agent 看得到的,别的名字让这一轮以错误结束。超时(60 秒)、抛错或插件进程不在时当它没表态,用下游的组装;声明了 `failClosed` 的这一轮以错误结束。dsh 0.2.2-rc.1 起载荷是 `PromptPresentation`,没有 `tools`;这里照 0.12 带着 `tools`;返回的对象没有 `tools` 时按没改工具处理(补上 `next()` 给的,没调用 `next()` 时补上收到的)。身份段 `deployment:persona-prefix` 可以改写、去掉(dsh 0.1.x 经组合补丁 `system-prompt` 行的 `config.persona` 换身份,FtAi 没有这一行,改成在这里换);回复语言规则是单独的一段 `deployment:reply-language`,宿主在瀑布之后把它原样固定回身份段之后,改写、去掉都不生效;插件注册的完整段就是整个系统提示,不带它' },
213
+ { legacy: 'system-prompt/change', status: 'same', sdk: 'system-prompt/change', note: '段、运行环境、变量、工具提供者与工具的注册变化时通知,异步发出,监听者看到的已是变化之后的状态' },
214
+ // ── 会话 ──
215
+ { legacy: 'ctx.sessions', status: 'changed', sdk: 'ctx.sessions', note: '插件记录改用 SDK 的 `appendPluginRecord()`(异步);读日志用句柄的 `session.readHeader()`、`readEvents()`、`readSurface()`、`readSeq()`;其余方法见各自一行,同步读取都变成 Promise;导出会话日志改用内部 SDK 的 `ctx.sessionLog.read(sessionId)`(只给一方插件)' },
216
+ { legacy: 'ctx.sessions.create', status: 'changed', sdk: 'ctx.sessions', awaited: 'call', note: '返回 Promise,只收 id 与 `meta.cwd`:`seed`、`inheritedEventCount` 与血缘字段报错(种子只经 `fork` 带入)。不再是内存里的会话:第一次写入时落盘,之后是普通会话,进会话目录。不发 `agent/created`,要驱动它用 `ctx.agents.resume`' },
217
+ { legacy: 'ctx.sessions.prepare', status: 'changed', sdk: 'ctx.sessions', awaited: 'call', note: '返回 Promise:校验 id 与 `meta.cwd`,不进内存。`enter` 之前句柄读不到、写不了这个会话(0.12 是能用的离线会话)' },
218
+ { legacy: 'ctx.sessions.enter', status: 'changed', sdk: 'ctx.sessions', awaited: 'call', note: '返回 Promise,结果是异步的放开函数;放开后下一次核对时(最长约 1 分钟)卸下,不是当场。`session/created` 在这里发' },
219
+ { legacy: 'ctx.sessions.announce', status: 'changed', sdk: 'ctx.sessions', awaited: 'call', note: '`session/created` 由宿主在 `enter` 时发,插件只监听,监听者不能否决;这里只等它发到监听者手里' },
220
+ { legacy: 'ctx.sessions.flush', status: 'same', sdk: 'ctx.sessions', note: '等已发出的 `session/event` 到了监听者手里,再按顺序等 `session/flush` 的监听者(0.12 并行),第一个失败的错误交回。宿主记事件时同步落盘,结果总是 true' },
221
+ { legacy: 'ctx.sessions.get', status: 'changed', sdk: 'ctx.sessions', awaited: 'call', note: '返回 Promise:宿主内存里的会话,没用到或已卸下时为 undefined' },
222
+ { legacy: 'ctx.sessions.list', status: 'changed', sdk: 'ctx.sessions', awaited: 'call', note: '返回 Promise:宿主内存里全部的会话,按建立的先后' },
223
+ { legacy: 'ctx.sessions.fork', status: 'changed', sdk: 'ctx.sessions', awaited: 'call', note: '返回 Promise,种子只经它带入。新会话落盘、发 `agent/created`、挂到来源所在的工作区。空的来源报 `session/fork-unavailable`(0.12 分出空会话);错误是宿主的错误码,没有 `SessionForkError`' },
224
+ { legacy: 'ctx.sessions.messageProjections', status: 'same', sdk: 'ctx.sessions', note: '本进程登记的消息投影,同步' },
225
+ { legacy: 'ctx.sessions.registerMessageProjection', status: 'changed', sdk: 'ctx.sessions', note: '只解释插件记录(`plugin:...`,`plugin:ftai/` 除外),只改 user、assistant、tool 消息的内容。在插件进程里跑,入参是 JSON 副本,可以返回 Promise;派生时宿主等它,抛错、超时(30 秒)或插件进程不在时这一步失败(插件进程正在起时先等它激活,崩溃后等待重启时直接失败)。写入不经过它(0.12 在追加时就校验)。撤销后记录被忽略,消息回到原文(0.12 拒绝派生)' },
226
+ { legacy: 'session/event', status: 'changed', sdk: 'session/event', todo: false, note: '参数是 `(session, event)`:会话句柄与会话文件里的 v4 行。不等监听者:监听者改成 async 之后,同一个会话的处理可能交错,要按顺序就自己排队。写之前读到的可能已经过期(`append` 没有条件写入),写之前再核对一次。dsh 0.1.2 及更早的会话格式是 v0(有 `assistant/chunk`、`tool/code-dispatch` 等),这里只有 v4;dsh 0.2.1-rc.2 起的 `job/registered`、`job/settled` 这里不写' },
227
+ { legacy: 'session/created', status: 'changed', sdk: 'session/created', todo: false, note: '参数是会话句柄;新建的、读进来查看或续上的都发。只是通知,监听者不能否决' },
228
+ { legacy: 'session/disposed', status: 'changed', sdk: 'session/disposed', todo: false, note: '参数是会话句柄;会话从宿主内存卸下(空闲 5 分钟)时发,再用到时再发一次 `session/created`' },
229
+ { legacy: 'session/flush', status: 'changed', sdk: 'session/flush', todo: false, note: '参数是会话句柄;每批写入后发,排在这批的 `session/event` 之后,监听者按顺序等(0.12 并行),超时 30 秒。写入不等它,失败只记日志;`ctx.sessions.flush` 时再发一次,第一个失败的错误交回调用方' },
230
+ { legacy: '@deepseek-ai/dsh-session#Session.id', status: 'same', sdk: `${HOST}#SessionHandle`, note: '字符串,不是品牌类型' },
231
+ { legacy: '@deepseek-ai/dsh-session#Session.header', status: 'changed', sdk: `${HOST}#SessionHandle`, note: '句柄的 `header` 只有 `cwd`(工作目录,换目录后跟着变);完整的会话头用 `await session.readHeader()`' },
232
+ { legacy: '@deepseek-ai/dsh-session#Session.surface', status: 'changed', sdk: `${HOST}#SessionHandle`, note: '`await session.readSurface()`:模型此刻看得到的事件,按顺序' },
233
+ { legacy: '@deepseek-ai/dsh-session#Session.eventAt', status: 'changed', sdk: `${HOST}#SessionHandle`, note: '`(await session.readEvents({ fromSeq: seq, toSeq: seq }))[0]`' },
234
+ { legacy: '@deepseek-ai/dsh-session#Session.snapshotEvents', status: 'changed', sdk: `${HOST}#SessionHandle`, note: '`await session.readEvents({ fromSeq, toSeq })`:两端都含,0.12 的上界不含' },
235
+ { legacy: '@deepseek-ai/dsh-session#Session.inheritedEventCount', status: 'changed', sdk: `${HOST}#SessionHandle`, awaited: 'read', note: '读属性得到 Promise,加 `await`' },
236
+ { legacy: '@deepseek-ai/dsh-session#Session.firstLiveSeq', status: 'changed', sdk: `${HOST}#SessionHandle`, awaited: 'read', note: '读属性得到 Promise,加 `await`:这次进内存时带来的事件数,卸下再读进来时会变' },
237
+ { legacy: '@deepseek-ai/dsh-session#Session.firstLifecycleSeq', status: 'changed', sdk: `${HOST}#SessionHandle`, awaited: 'read', note: '读属性得到 Promise,加 `await`' },
238
+ { legacy: '@deepseek-ai/dsh-session#Session.ownEvents', status: 'changed', sdk: `${HOST}#SessionHandle`, awaited: 'call', note: '返回 Promise,加 `await`:这个会话自己写下的事件,不含继承的' },
239
+ { legacy: '@deepseek-ai/dsh-session#Session.isOwnSeq', status: 'changed', sdk: `${HOST}#SessionHandle`, awaited: 'call', note: '返回 Promise,加 `await`' },
240
+ { legacy: '@deepseek-ai/dsh-session#Session.seq', status: 'changed', sdk: `${HOST}#SessionHandle`, note: '`await session.readSeq()`:下一个事件的 seq,即日志长度' },
241
+ { legacy: '@deepseek-ai/dsh-session#Session.append', status: 'changed', sdk: `${HOST}#SessionHandle`, awaited: 'call', note: '返回 Promise,加 `await`。只收插件记录的类型(`plugin:...`),一律可忽略;核心类型与别的类型报 `session/event-type-not-allowed`,没有 `surfaceOp`:会话格式 v4 冻结,模型可见的内容用消息投影改' },
242
+ { legacy: '@deepseek-ai/dsh-session#Session.requestHeader', status: 'changed', sdk: `${HOST}#SessionHandle`, awaited: 'call', note: '返回 Promise,加 `await`:最近一段请求的头(配置与工具清单);只要这一步的模型时读 `exec.model`' },
243
+ { legacy: '@deepseek-ai/dsh-session#Session.requestContext', status: 'changed', sdk: `${HOST}#SessionHandle`, awaited: 'call', note: '返回 Promise,加 `await`:最新的 provider、model 与上下文窗口' },
244
+ { legacy: '@deepseek-ai/dsh-session#Session.toolHistory', status: 'changed', sdk: `${HOST}#SessionHandle`, awaited: 'call', note: '返回 Promise,加 `await`:每次从日志整份折叠' },
245
+ { legacy: '@deepseek-ai/dsh-session#Session.deriveMessages', status: 'changed', sdk: `${HOST}#SessionHandle`, awaited: 'call', note: '返回 Promise,加 `await`:消息投影已生效,日志不变;投影失败时拒绝' },
246
+ { legacy: '@deepseek-ai/dsh-session#Session.deriveEventMessage', status: 'changed', sdk: `${HOST}#SessionHandle`, awaited: 'call', note: '返回 Promise,加 `await`;失败同 `deriveMessages`' },
247
+ { legacy: 'ctx.sessionProjections', status: 'changed', sdk: 'ctx.sessionProjections', note: '`register()` 照旧(reducer 在插件进程里运行);`stateOf()` 与要折叠的读法改为异步,codemod 自动加 `await`;检查点宿主不托管,跨重启由插件自己存;界面读视图用插件自己的 remote。dsh 0.2.2-rc.1 起的 `onEventChanged`、`summaryKeys` 不提供' },
248
+ { legacy: 'ctx.sessionProjections.register', status: 'same', sdk: 'ctx.sessionProjections', note: '带 `wire` 的重载照旧,视图只在插件进程里算;`init` 的第二个参数是继承来的事件数。dsh 0.2.2-rc.1 起返回 `Promise<ProjectionHandle>`(`stateOf`、`readerFor`、`dispose`);这里照 0.12 返回撤销函数,读状态用 `await ctx.sessionProjections.stateOf(session, key)`' },
249
+ { legacy: 'ctx.sessionProjections.stateOf', status: 'changed', sdk: 'ctx.sessionProjections', awaited: 'call', note: '返回 Promise:`await ctx.sessionProjections.stateOf(session, key)`,所在的监听者改成 async。内置单元只有 `turnBoundary`(同 0.12),别的 0.12 单元(如 `plan`、`goal`、`modelSelection`)由它们的插件提供,没有时是 undefined' },
250
+ { legacy: 'ctx.sessionProjections.onChanged', status: 'same', sdk: 'ctx.sessionProjections', note: '只通知实时事件引起的变化,整批回放不通知;有订阅时每个有新事件的会话都会折叠一次' },
251
+ { legacy: 'ctx.sessionProjections.snapshot', status: 'changed', sdk: 'ctx.sessionProjections', awaited: 'call', note: '返回 Promise,加 `await`:各单元来自同一个游标,`asOfSeq` 是这个进程折叠到的事件,可能落后于还在路上的事件' },
252
+ { legacy: 'ctx.sessionProjections.cachedSnapshot', status: 'same', sdk: 'ctx.sessionProjections', note: '同步:只读已折叠的视图,没折叠时为 undefined' },
253
+ { legacy: 'ctx.sessionProjections.checkpoint', status: 'changed', sdk: 'ctx.sessionProjections', awaited: 'call', note: '返回 Promise,加 `await`' },
254
+ { legacy: 'ctx.sessionProjections.restoreFloor', status: 'same', sdk: 'ctx.sessionProjections' },
255
+ { legacy: 'ctx.sessionProjections.viewCheckpoint', status: 'same', sdk: 'ctx.sessionProjections' },
256
+ { legacy: 'ctx.sessionProjections.restore', status: 'same', sdk: 'ctx.sessionProjections', note: '尾部用 `await session.readEvents({ fromSeq })` 取' },
257
+ { legacy: 'ctx.sessionProjections.hydrate', status: 'changed', sdk: 'ctx.sessionProjections', awaited: 'call', note: '返回 Promise,加 `await`:恢复后跟着 `session/event` 继续' },
258
+ // ── 文件与附件 ──
259
+ { legacy: 'ctx.fs', status: 'changed', sdk: 'ctx.fs', note: '写文件用 `ctx.fs.writeBytes(target, bytes, options)` 或 `ctx.fs.writeText(target, text, options)`,编辑用 `ctx.fs.editText(target, edit, options)`,宿主在改之前跑 `fs/write-intent`、`fs/edit-intent`;没有 `sandboxMode`;读取的 `signal` 中止时抛 `signal.reason`,不是 `FS_ABORTED`;`readText`、`readByteRange`、`listDir` 带上限,见各自一行。dsh 0.2.2-rc.1 起的 `patchText`、`deleteFile`、`moveFile` 与 `fs/delete-intent` 不提供' },
34
260
  { legacy: 'ctx.fs.resolve', status: 'same', sdk: 'ctx.fs' },
35
261
  { legacy: 'ctx.fs.stat', status: 'same', sdk: 'ctx.fs' },
36
262
  { legacy: 'ctx.fs.readBytes', status: 'same', sdk: 'ctx.fs', note: '超过 `maxBytes` 报 `FS_TOO_LARGE`' },
37
- { legacy: 'ctx.fs.processPath', status: 'same', sdk: 'ctx.fs', note: '照旧是同步的;只认本进程 `ctx.fs.resolve()` 得到的目标' },
38
- { legacy: 'ctx.fs.sandboxMode', status: 'removed', note: '插件不再自己围沙箱写二进制:改用 `ctx.fs.writeBytes(target, bytes, { execution, expected })`,由宿主写。工具自带的 `sandbox_permissions`、`justification` 与审批换成工具定义的 `sandboxEscalation: true`:宿主加上这两个参数,执行之前经审批定下这一次的模式,`writeBytes` 带着这次调用写入时沿用' },
39
- { legacy: 'ctx.shell', status: 'pending', note: '线 A 工具与权限:在会话的沙箱里执行命令' },
40
- { legacy: 'ctx.web', status: 'pending', note: '线 B 第 5 批(web-fetch-http、web-search)' },
41
- { legacy: 'ctx.jobs', status: 'pending', note: '线 A 工具:工具的后台任务' },
42
- { legacy: 'ctx.approval', status: 'changed', sdk: 'ctx.approval', note: '内部 SDK,只给一方插件:`await ctx.approval.request(execution, reason, displayReason)`,`execution` 是进行中工具调用的 `exec.token`,只能为自己正在执行的这次调用申请;结论照旧是四种之一,审批策略 never 与「替我审批」的会话直接拒绝;拦截工具调用时优先在 `tools/pre-execute` 返回 `{ kind: \'ask\' }`' },
43
- { legacy: 'ctx.userQuestions', status: 'pending', note: '线 A Loop:向用户提问' },
44
- { legacy: 'ctx.storageDomain', status: 'pending', note: '插件自己的结构化数据:宿主尚未提供,归属待定' },
45
- { legacy: 'ctx.credentials', status: 'pending', note: '线 B 第 1 批(credentials-keyring)给 TS 插件的那一层尚未进扩展点表' },
263
+ { legacy: 'ctx.fs.processPath', status: 'same', sdk: 'ctx.fs', note: '照旧是同步的;只认本进程 `resolve`、`listDir` 或 `fs/*` 扩展点给的目标' },
264
+ { legacy: 'ctx.fs.processPathFromHostPath', status: 'same', sdk: 'ctx.fs', note: '插件进程与宿主在同一个文件系统上:绝对路径原样给出(不做 realpath),其余为 undefined' },
265
+ { legacy: 'ctx.fs.writeText', status: 'changed', sdk: 'ctx.fs', note: '参数改为 `(target, content, { execution, expected, signal })`,按 UTF-8 写;不再收 `sandboxPolicy`:带上 `execution` 时宿主按这次工具调用的沙箱围住,不带时按部署默认的模式(同 0.12)' },
266
+ { legacy: 'ctx.fs.sandboxMode', status: 'removed', note: '插件不再自己围沙箱写二进制:改用 `ctx.fs.writeBytes(target, bytes, { execution, expected })`,由宿主写。工具自带的 `sandbox_permissions`、`justification` 与审批换成工具定义的 `sandboxEscalation: true`:宿主加上这两个参数,执行之前经审批定下这一次的模式,`writeBytes` 带着这次调用写入时沿用;要读会话的沙箱模式用阶段 3 的 `ctx.sandboxPolicy`' },
267
+ { legacy: 'ctx.fs.watch', status: 'same', sdk: 'ctx.fs', note: '`signal` 随时能停(0.12 只管初始化),调用方的作用域撤销时同样停止;200ms 内的变化合并成一次;系统监听挂不上时不报错,只是收不到变化' },
268
+ { legacy: 'ctx.fs.fileUrl', status: 'same', sdk: 'ctx.fs', note: '照旧是同步的;只认本进程 `resolve`、`listDir` 或 `fs/*` 扩展点给的目标' },
269
+ { legacy: 'ctx.fs.contains', status: 'same', sdk: 'ctx.fs', note: '照旧是同步的;目标的要求同 `fileUrl`' },
270
+ { legacy: 'ctx.fs.lstat', status: 'same', sdk: 'ctx.fs' },
271
+ { legacy: 'ctx.fs.readText', status: 'same', sdk: 'ctx.fs', note: '超过 10 MiB 报 `FS_TOO_LARGE`,更大的文件用 `streamText`' },
272
+ { legacy: 'ctx.fs.streamText', status: 'same', sdk: 'ctx.fs', note: '不限大小;一块向宿主要一次,调用方不要下一块时宿主不多读' },
273
+ { legacy: 'ctx.fs.readByteRange', status: 'same', sdk: 'ctx.fs', note: '`length` 超过 10 MiB 报 `FS_TOO_LARGE`' },
274
+ { legacy: 'ctx.fs.listDir', status: 'same', sdk: 'ctx.fs', note: '超过 10000 项报 `FS_TOO_LARGE`,不返回截断的清单' },
275
+ { legacy: 'ctx.fs.editText', status: 'changed', sdk: 'ctx.fs', note: '参数改为 `(target, edit, { execution, expected, signal })`,不再收 `sandboxPolicy`,也不用自己跑 `fs/edit-intent`。带 `execution` 时宿主跑它并用它的结论(这个会话的文件工具要读过这个文件,插件读过不算),沙箱按这次调用,改完发 `fs/observed`;不带时是插件自己的改动,不跑瀑布,按部署默认的模式围住(同 0.12)。`writeBytes` 不同:它只看调用方给的 `expected`' },
276
+ { legacy: 'fs/write-intent', status: 'changed', sdk: 'fs/write-intent', note: '`ctx.on` 照旧,`actor` 是工具调用的句柄;不管写没写 `prepend` 都排在最前。写文件工具走它时只能收紧:返回的条件与先读后改都要满足,不调用 `next` 时宿主照样跑下游,条件冲突时这次写入失败;抛 `FsError` 时以它结束;其他错误、超时或插件进程不在时当它没表态,声明了 `failClosed` 的以 `FS_IO_ERROR` 结束。插件不能发起;`ctx.fs.writeBytes`、`writeText` 在写之前也跑它,但只认它的报错,不用它返回的条件与先读后改' },
277
+ { legacy: 'fs/edit-intent', status: 'changed', sdk: 'fs/edit-intent', note: '同 `fs/write-intent`:只能收紧,失败当它没表态,声明了 `failClosed` 的这次编辑失败。插件不能发起,编辑用 `ctx.fs.editText`,宿主在改之前跑它' },
278
+ { legacy: 'fs/observed', status: 'changed', sdk: 'fs/observed', note: '只能监听,`actor` 是工具调用的句柄。`ctx.emit` 到不了宿主:插件读过文件不算观察,放宽不了先读后改' },
279
+ { legacy: 'ctx.attachments', status: 'changed', sdk: 'ctx.attachments', note: '`imageHostPath`、`fileHostPath` 变成 Promise,`isAttachmentError` 改用 SDK 导出的函数,其余同名同形' },
280
+ { legacy: 'ctx.attachments.saveImages', status: 'same', sdk: 'ctx.attachments', note: '`data` 是 `Uint8Array`;失败抛 `AttachmentError`,`isImageAdmissionError` 照旧' },
281
+ { legacy: 'ctx.attachments.isAttachmentError', status: 'changed', sdk: `${HOST}#isAttachmentError`, note: '`import { isAttachmentError } from \'@ftai/plugin-sdk/host\'`,调用处去掉 `ctx.attachments.` 前缀' },
282
+ { legacy: 'ctx.attachments.imageLimits', status: 'same', sdk: 'ctx.attachments', note: '照旧是同步属性:服务提供时从宿主读的快照,宿主里是常量,不会过期' },
283
+ { legacy: 'ctx.attachments.validateImage', status: 'same', sdk: 'ctx.attachments' },
284
+ { legacy: 'ctx.attachments.admitPromptContent', status: 'same', sdk: 'ctx.attachments' },
285
+ { legacy: 'ctx.attachments.admitEncodedFile', status: 'same', sdk: 'ctx.attachments' },
286
+ { legacy: 'ctx.attachments.saveImage', status: 'same', sdk: 'ctx.attachments' },
287
+ { legacy: 'ctx.attachments.readImage', status: 'same', sdk: 'ctx.attachments' },
288
+ { legacy: 'ctx.attachments.imageHostPath', status: 'changed', sdk: 'ctx.attachments', awaited: 'call', note: '返回 Promise,加 `await`:要问宿主' },
289
+ { legacy: 'ctx.attachments.saveFile', status: 'same', sdk: 'ctx.attachments' },
290
+ { legacy: 'ctx.attachments.saveFileStream', status: 'same', sdk: 'ctx.attachments', note: '每块最多 64 KiB 地发给宿主;中止、失败、两块之间超过 5 分钟没有新块或插件进程退出时暂存的内容删除' },
291
+ { legacy: 'ctx.attachments.readFileStream', status: 'same', sdk: 'ctx.attachments', note: '每块最多 64 KiB;摘要不符时迭代以 `ATTACHMENT_CORRUPT` 结束' },
292
+ { legacy: 'ctx.attachments.fileHostPath', status: 'changed', sdk: 'ctx.attachments', awaited: 'call', note: '返回 Promise,加 `await`:要问宿主' },
293
+ { legacy: 'ctx.attachments.readImageRequest', status: 'same', sdk: 'ctx.attachments' },
294
+ // ── 平台服务 ──
295
+ { legacy: 'ctx.commands', status: 'changed', sdk: 'ctx.commands', note: '宿主的命令表,界面并进输入框的斜杠建议;只有界面用的斜杠命令仍可用界面一半的 `slashCommands`,它与 `/goal`、`/compact`、`/mcp`、`/init` 优先。见下面各行' },
296
+ { legacy: 'ctx.commands.register', status: 'changed', sdk: 'ctx.commands', note: '定义同 0.12,`input` 不收 `attachments`(写了当场抛错),调用里的 `attachments` 总是空的;`sourceEventSeq` 与 `recordInput` 照旧。写法错误当场抛,同一层里重名由宿主判定:激活期间被拒时插件加载失败,之后的从返回句柄的 `ready` 报。`agent.ctx.commands.register` 只对那个 agent 生效' },
297
+ { legacy: 'ctx.commands.list', status: 'changed', sdk: 'ctx.commands', awaited: 'call', note: '`list(sessionId)`:收会话 id,不收 agent;返回 Promise,加 `await`' },
298
+ { legacy: 'ctx.commands.find', status: 'changed', sdk: 'ctx.commands', awaited: 'call', note: '`find(sessionId, name)`:收会话 id,只给描述,处理函数过不了进程;返回 Promise,加 `await`' },
299
+ { legacy: 'ctx.commands.execute', status: 'changed', sdk: 'ctx.commands', note: '`execute(sessionId, line, signal?)`:收会话 id,没有附件参数。处理函数抛错时以 `COMMAND_FAILED` 拒绝,不是原来的错误对象;`command/done` 的 `text` 没有时记空串' },
300
+ { legacy: 'ctx.commands.registerFileReceiptResolver', status: 'removed', note: '命令不收附件,也就没有上传凭据要解析' },
301
+ { legacy: 'commands/change', status: 'same', sdk: 'commands/change' },
302
+ { legacy: 'ctx.skills', status: 'changed', sdk: 'ctx.skills', note: '读的是模型看到的同一份,受用户的开关管。见下面各行' },
303
+ { legacy: 'ctx.skills.list', status: 'changed', sdk: 'ctx.skills', note: '选项只有 `cwd`、`signal`,没有 `scope`(宿主不按 agent 分层);`source` 是 `repo`、`user`、`pack`、`system` 或注册时给的值,`provider` 是 `filesystem` 或插件名' },
304
+ { legacy: 'ctx.skills.snapshot', status: 'changed', sdk: 'ctx.skills', note: '同 `list`;有读不了的条目或目录时 `complete` 为 false,读到的照样给出' },
305
+ { legacy: 'ctx.skills.get', status: 'changed', sdk: 'ctx.skills', note: '同 `list`' },
306
+ { legacy: 'ctx.skills.register', status: 'changed', sdk: 'ctx.skills', note: '定义同 0.12,没有 `provider`(固定是插件名)。进 Skill 目录、用户的开关与管理页,优先级在项目的之后、用户的之前。只能全局注册(`agent.ctx` 上抛错);插件之间重名是错误(0.12 是后注册的被忽略),激活期间被拒时插件加载失败,之后的从返回句柄的 `ready` 报;没有 `resourceBase` 时模型看不到提供方的名字' },
307
+ { legacy: 'ctx.skills.registerProvider', status: 'pending', note: '阶段 3 不做:提供方要动态列出与加载 Skill,每一步组装都要跨进程问它,且第三方的目录与内置的怎么排、能不能盖住要用户定;要加一个 Skill 用 `register`' },
308
+ { legacy: 'skills/change', status: 'same', sdk: 'skills/change', note: '开关、安装卸载、能力包、插件注册都通知;磁盘上的改动从这个插件进程第一次读 Skill 起才通知,读过的工作目录才盯' },
309
+ { legacy: 'ctx.shell', status: 'changed', sdk: 'ctx.shell', note: '`resolve(req)`、`execute(spec)` 都是 Promise,`request` 带 `execution`(进行中工具调用的句柄,同 `ctx.fs`)时按这次调用定下的模式,不带时按部署默认的模式(`defaultMode()`,同 0.12),都断网。必须过沙箱:`sandboxPolicy` 不收,写了报 `invalid_params`,`dshEnv`、`stdoutMaxBytes` 同样(完整输出看 `spillPath`);`onExpiry` 只有 `kill`,上限 10 分钟。不弹审批;命令规则禁止的报 `COMMAND_FORBIDDEN`,没有可用的运行器抛 `SandboxUnavailableError`(Windows 上只有完全访问的调用能跑)。句柄的 `readOutput()`、`kill()` 是 Promise,没有 `observed`;`sandboxMode` 不提供,用 `ctx.sandboxPolicy`。命令随插件撤销停下' },
310
+ { legacy: 'ctx.shell.resolve', status: 'changed', sdk: 'ctx.shell', awaited: 'call', note: '返回 Promise,加 `await`;不收 `sandboxPolicy`,带 `execution` 时按这次工具调用定下的模式' },
311
+ { legacy: 'ctx.shell.sandboxMode', status: 'removed', note: '不提供:读这次调用定下的模式用 `await ctx.sandboxPolicy.resolve({ sessionId, execution })`,不带 `execution` 的默认模式用 `await ctx.sandboxPolicy.defaultMode()`' },
312
+ { legacy: 'ctx.sandbox', status: 'changed', sdk: 'ctx.sandbox', note: '`await ctx.sandbox.confine(argv, policy, signal)`,形状同 0.12。模式只收 `read-only`、`workspace-write`,完全访问报 `invalid_params`;没有可用的运行器(Windows 现状)抛 `SandboxUnavailableError`,绝不回退成不围。`enforcement` 总是 `full`,`runnerFailureRules` 只有 `fatalSignatures`' },
313
+ { legacy: 'ctx.web', status: 'changed', sdk: 'ctx.web', note: '只有 `search`、`fetch`,见下面各行;错误类 `WebError` 从 `@ftai/plugin-sdk/host` 引入。dsh 0.2.2-rc.1 起的 `searchReady`、`fetchReady` 不提供' },
314
+ { legacy: 'ctx.web.search', status: 'same', sdk: 'ctx.web', note: '用当前登录的 FtAi 账号与额度,同 `web_search` 工具;没有登录时报 `WEB_PROVIDER_CREDENTIAL_MISSING`。服务端单次最多给 10 条,`maxResults` 再大也只有这么多' },
315
+ { legacy: 'ctx.web.fetch', status: 'same', sdk: 'ctx.web', note: '同 `web_fetch` 工具的地址校验与上限,正文不排版;非 2xx 也是结果,不抛错(工具把它们记成失败)' },
316
+ { legacy: 'ctx.web.registerSearchProvider', status: 'pending', note: '阶段 3 不做:替换内置搜索要用户定' },
317
+ { legacy: 'ctx.web.registerFetchProvider', status: 'pending', note: '阶段 3 不做:替换内置抓取要用户定' },
318
+ { legacy: 'ctx.jobs', status: 'changed', sdk: 'ctx.jobs', note: '成员见各自一行,跨进程后都返回 Promise。`caller` 同 0.12:归属会话的任务只有那个会话读得到,不给时只看得到不归属会话的。`events` 的 `{ owners: \'scope\' }` 在 `agent.ctx` 上是这个 agent 的,否则是全部。没有 `attachController`' },
319
+ { legacy: 'ctx.jobs.start', status: 'changed', sdk: 'ctx.jobs', awaited: 'call', note: '返回 Promise,加 `await`:`run` 在宿主留下 id 之后才调用,不在这次调用里同步跑;`run` 抛错时什么也不留。上限按插件名算,每个插件同时最多 10 个(0.12 按归属的会话),不占会话的名额。`owner` 是会话 id,不存在时报 `agent/session-not-found`。工作跑在插件进程里:插件撤销时任务被取消(最多等 5 秒,等不到按失败结束),插件进程退出时任务按失败结束' },
320
+ { legacy: 'ctx.jobs.list', status: 'changed', sdk: 'ctx.jobs', awaited: 'call', note: '返回 Promise,加 `await`' },
321
+ { legacy: 'ctx.jobs.get', status: 'changed', sdk: 'ctx.jobs', awaited: 'call', note: '返回 Promise,加 `await`' },
322
+ { legacy: 'ctx.jobs.read', status: 'changed', sdk: 'ctx.jobs', awaited: 'call', note: '返回 Promise,加 `await`' },
323
+ { legacy: 'ctx.jobs.readAt', status: 'changed', sdk: 'ctx.jobs', awaited: 'call', note: '返回 Promise,加 `await`' },
324
+ { legacy: 'ctx.jobs.kill', status: 'changed', sdk: 'ctx.jobs', awaited: 'call', note: '返回 Promise,加 `await`。生产方的 `cancel` 抛错时抛不回发起方:只记日志,任务留在 `stopping`' },
325
+ { legacy: 'ctx.jobs.wait', status: 'same', sdk: 'ctx.jobs' },
326
+ { legacy: 'ctx.jobs.remove', status: 'changed', sdk: 'ctx.jobs', awaited: 'call', note: '返回 Promise,加 `await`' },
327
+ { legacy: 'ctx.jobs.events', status: 'same', sdk: 'ctx.jobs', note: '订阅随调用者撤销;事件异步送达,不在提交时同步派发' },
328
+ { legacy: 'ctx.jobs.attachController', status: 'pending', note: '阶段 3:要用户定。宿主的 job 工具随 Agent 核心在,`start` 不要求有控制器;0.12 没有控制器时拒绝 `start`,这个接口只为声明「有人能收任务」' },
329
+ { legacy: '@deepseek-ai/dsh-jobs#JobId', status: 'same', sdk: `${HOST}#JobId`, brand: true, note: '就是字符串:`JobId(...)` 包装由 codemod 去掉' },
330
+ { legacy: '@deepseek-ai/dsh-jobs#JobRegistry', status: 'changed', sdk: `${HOST}#JobRegistry`, todo: false, note: '接口,不是要继承的类:不能提供第二个实现;方法都返回 Promise' },
331
+ { legacy: '@deepseek-ai/dsh-jobs#JobSpec', status: 'same', sdk: `${HOST}#JobSpec` },
332
+ { legacy: '@deepseek-ai/dsh-jobs#JobHandle', status: 'same', sdk: `${HOST}#JobHandle`, note: '写入照旧是同步的:发出去不等答复,按调用的顺序生效' },
333
+ { legacy: '@deepseek-ai/dsh-jobs#JobHooks', status: 'same', sdk: `${HOST}#JobHooks` },
334
+ { legacy: '@deepseek-ai/dsh-jobs#JobOutcome', status: 'same', sdk: `${HOST}#JobOutcome` },
335
+ { legacy: '@deepseek-ai/dsh-jobs#JobView', status: 'same', sdk: `${HOST}#JobView` },
336
+ { legacy: '@deepseek-ai/dsh-jobs#JobEvent', status: 'same', sdk: `${HOST}#JobEvent` },
337
+ { legacy: '@deepseek-ai/dsh-jobs#JobOutputSource', status: 'same', sdk: `${HOST}#JobOutputSource`, note: '在插件进程里每 150 毫秒读一次' },
338
+ { legacy: 'ctx.approval', status: 'changed', sdk: 'ctx.approval', note: '四个成员都有,都是 Promise,见各自一行;拦截工具调用时优先在 `tools/pre-execute` 返回 `{ kind: \'ask\' }`' },
339
+ { legacy: 'ctx.approval.request', status: 'changed', sdk: 'ctx.approval', note: '`await ctx.approval.request(execution, reason, displayReason)`,`execution` 是进行中工具调用的句柄(同 `ctx.fs`),只能为这次调用申请,不收 agent 与 signal(这一轮取消时结论是 `cancelled`);结论照旧是四种之一,审批策略 never 与「替我审批」的会话直接拒绝' },
340
+ { legacy: 'ctx.approval.config', status: 'changed', sdk: 'ctx.approval', note: '从属性改成方法:`await ctx.approval.config()`,得到 `{ policy }`' },
341
+ { legacy: 'ctx.approval.overrideOf', status: 'changed', sdk: 'ctx.approval', awaited: 'call', note: '返回 Promise,加 `await`;参数是会话 id;没有记录时是 undefined' },
342
+ { legacy: 'ctx.approval.setPolicy', status: 'changed', sdk: 'ctx.approval', awaited: 'call', note: '返回 Promise,加 `await`;第一个参数是会话 id。相同值不写,子 agent 的会话报 `agent/subagent-session`。写下的事件带调用方插件名;给模型的通知不说是用户改的(0.12 写 `changed by the user`)' },
343
+ { legacy: 'approval/request', status: 'changed', sdk: 'approval/request', note: '载荷的 `agent` 换成 `sessionId`,有 `toolName`、`callId`、`reason`、`displayReason`、`signal`,同 0.12 不带参数原文;`next()` 不能改载荷。「替我审批」与 never 的会话不派发。答 `allowed-once` 等于用户批准这一次,包括提权;记下作答的插件。与 0.12 不同:`next()` 给出拒绝或取消之后改成 `allowed-once` 不算数,照 `next()` 的结论(`next()` 是 `unavailable` 时照样可以作答)。抛错、崩溃、自身用时超过 60 秒(等 `next()` 的时间不算)、返回值不是四种之一时当它没表态,交给下一个(最后是用户的卡片),已经拿到 `next()` 的结论时用它;声明了 `failClosed` 的是 `unavailable`,不转下一个' },
344
+ { legacy: 'ctx.userQuestions', status: 'changed', sdk: 'ctx.userQuestions', note: '与模型的 `ask_user_question` 同一条路,界面出同样的卡片。见下面各行;错误类 `UserQuestionError` 从 `@ftai/plugin-sdk/host` 引入' },
345
+ { legacy: 'ctx.userQuestions.ask', status: 'changed', sdk: 'ctx.userQuestions', note: '收 `sessionId`,不收 `agent`;`wait.callId` 不给时宿主生成一个。不在进行中的一轮里也能问:卡片显示在那个会话里,4 分钟没回答按关掉(`ASK_CANCELLED`);手机端只在进行中的一轮里显示' },
346
+ { legacy: 'ctx.userQuestions.answer', status: 'changed', sdk: 'ctx.userQuestions', note: '`answer(sessionId, callId, answer)`:收会话 id,返回 Promise。回答任何正在等待的提问(0.12 只回答超时后转入后台的),不写会话,界面的卡片撤回;没有在等时为 false' },
347
+ { legacy: 'ctx.userQuestions.askTimed', status: 'pending', note: '阶段 3 不做:宿主没有移植 timed 模式(0.12 也没有启用),要先加转入后台的提问与补交回答的会话写法;要限时就给 `ask` 传 `signal`' },
348
+ { legacy: 'ctx.userQuestions.attachWait', status: 'pending', note: '阶段 3 不做:只服务 timed 模式,见 `ctx.userQuestions.askTimed` 一行' },
349
+ { legacy: 'user-questions/request', status: 'changed', sdk: 'user-questions/request', note: '载荷收 `sessionId`,不收 `agent`;`wait` 总有 `callId`,没有 `timed`。可以替用户作答。不同于 0.12:监听者抛错、超时(60 秒,等 `next()` 的时间不算)或插件进程不在时不算作答,交给下一个,最后到界面的卡片' },
350
+ { legacy: 'ctx.storage', status: 'changed', sdk: 'ctx.storage', todo: false, note: '只有 `domain`,同 `ctx.storageDomain`;后端与挂载不开放,见各自一行' },
351
+ { legacy: 'ctx.storage.backend', status: 'removed', note: '不开放:域的落盘由插件进程定,文件格式同 0.12 的 JSON 后端。用 `ctx.storageDomain`' },
352
+ { legacy: 'ctx.storage.mount', status: 'removed', note: '不开放:只有域这一种数据形式。用 `ctx.storageDomain`' },
353
+ { legacy: 'ctx.storage.form', status: 'removed', note: '不开放:只有域这一种数据形式。用 `ctx.storageDomain`' },
354
+ { legacy: 'ctx.storageDomain', status: 'changed', sdk: 'ctx.storageDomain', todo: false, note: '`open`、`get`、`closeAll` 与域的读写同 0.12:读同步取内存,写落盘后才改内存。按插件隔离:每个插件一个数据目录,同名的域互不相干,碰不到核心的域;0.12 的旧文件不迁移,卸载插件时数据留下。句柄绑在打开它的作用域上,撤销时等写链落盘再关,不用自己 `close`。`facet-unsupported` 不再有' },
355
+ { legacy: 'domain/changed', status: 'changed', sdk: 'domain/changed', todo: false, note: '载荷与顺序同 0.12,落盘之后发。只发给拥有这个域的插件自己,不广播;核心的域(0.12 的 `workspace` 等)不发' },
356
+ { legacy: 'ctx.credentials', status: 'changed', sdk: 'ctx.credentials', todo: false, note: '方法名、参数与结果同 0.12(本来就是异步的),用法不用改。按插件隔离:记录与 `set`、`unset` 只在这个插件自己的空间里,照 0.12 写的地址存在这个插件名下,看不到别的插件与 FtAi 自己的记录;`resolve`、`describe` 先查自己的空间,再查插件进程的启动环境,别人保管的引用(FtAi 里配的提供方密钥、别的插件存的、0.12 留下的)要用户在界面上允许才读得到,没允许时按没配置返回、不等待。一方插件读别人保管的不要允许。0.12 写下的记录与引用不迁进插件的空间,要重新写(如重新授权)。卸载插件时它的空间与允许清掉。隔离只在接口这一层,挡不住直接读进程内存或存储的插件' },
357
+ { legacy: 'ctx.credentials.resolve', status: 'changed', sdk: 'ctx.credentials', todo: false, note: '分层变了:自己的空间、插件进程的启动环境、别人保管的(FtAi 的存储,再是别的插件的空间),0.12 是启动环境在最前。别人保管的没允许时是 undefined,界面提示用户,允许之后下一次调用就读得到;拿不到值的插件照 0.12 按没配置处理即可。来源是 `plugin`、`env`、`keyring` 或 `file`' },
358
+ { legacy: 'ctx.credentials.describe', status: 'changed', sdk: 'ctx.credentials', todo: false, note: '分层与允许同 `resolve`:没允许的别人保管的引用是 `configured: false`。`writable` 总是 true:写进自己的空间,排在启动环境之前' },
359
+ { legacy: 'ctx.credentials.set', status: 'changed', sdk: 'ctx.credentials', todo: false, note: '写进这个插件自己的空间,不写 FtAi 的存储;自己的空间排在启动环境之前,不再因被启动环境遮蔽而拒绝。空值照旧拒绝(用 `unset`)' },
360
+ { legacy: 'ctx.credentials.unset', status: 'same', sdk: 'ctx.credentials', note: '只删这个插件自己空间里的' },
361
+ { legacy: 'ctx.credentials.readRecord', status: 'same', sdk: 'ctx.credentials', note: '只读这个插件自己的记录' },
362
+ { legacy: 'ctx.credentials.describeRecord', status: 'same', sdk: 'ctx.credentials', note: '只看这个插件自己的记录' },
363
+ { legacy: 'ctx.credentials.listRecords', status: 'same', sdk: 'ctx.credentials', note: '只列这个插件自己的记录,按地址排好;列不出别的插件留下的' },
364
+ { legacy: 'ctx.credentials.modifyRecord', status: 'changed', sdk: 'ctx.credentials', todo: false, note: '同 0.12 在锁里读—改—写,写法不用改。`mutate` 跑在插件进程里,期间宿主持着存储的锁,30 秒内要给出结论,否则这次改动失败(`credentials/modify-timeout`),什么也不写;`mutate` 抛错时同样不写。`mutate` 里不能再写这个插件自己的凭据空间(要等同一把锁,直到 30 秒超时;0.12 同样不可重入)' },
365
+ { legacy: 'ctx.credentials.deleteRecord', status: 'same', sdk: 'ctx.credentials', note: '只删这个插件自己的记录' },
366
+ { legacy: 'credentials/reference-updated', status: 'changed', sdk: 'credentials/reference-updated', todo: false, note: '参数同 0.12。只发给读得到这一项的插件:自己空间里的写入只给自己;FtAi 或别的插件存的写入给一方插件与允许过它的插件;用户允许或撤销时给那个插件。只有本宿主里的写入,启动环境的变化观察不到' },
367
+ { legacy: 'credentials/record-updated', status: 'changed', sdk: 'credentials/record-updated', todo: false, note: '参数同 0.12(插件写的地址)。只发给写它的插件自己' },
368
+ { legacy: '@deepseek-ai/dsh-credentials#credentialRef', status: 'same', sdk: `${HOST}#credentialRef`, note: '同样校验,不合文法时抛 `TypeError`;返回的就是字符串' },
369
+ { legacy: '@deepseek-ai/dsh-credentials#credentialKey', status: 'same', sdk: `${HOST}#credentialKey`, note: '同样校验,不合文法时抛 `TypeError`;返回的就是字符串' },
370
+ { legacy: '@deepseek-ai/dsh-credentials#parseCredentialKey', status: 'same', sdk: `${HOST}#parseCredentialKey` },
371
+ { legacy: '@deepseek-ai/dsh-credentials#isCredentialRefName', status: 'same', sdk: `${HOST}#isCredentialRefName` },
372
+ { legacy: '@deepseek-ai/dsh-credentials#isCredentialKeySegment', status: 'same', sdk: `${HOST}#isCredentialKeySegment` },
373
+ { legacy: '@deepseek-ai/dsh-credentials#credentialKeyScope', status: 'same', sdk: `${HOST}#credentialKeyScope` },
374
+ { legacy: '@deepseek-ai/dsh-credentials#credentialKeyId', status: 'same', sdk: `${HOST}#credentialKeyId` },
375
+ { legacy: '@deepseek-ai/dsh-credentials#CredentialRef', status: 'same', sdk: `${HOST}#CredentialRef`, note: '0.12 的品牌类型,SDK 里就是字符串' },
376
+ { legacy: '@deepseek-ai/dsh-credentials#CredentialKey', status: 'same', sdk: `${HOST}#CredentialKey`, note: '0.12 的品牌类型,SDK 里就是字符串' },
377
+ { legacy: '@deepseek-ai/dsh-credentials#CredentialRecord', status: 'same', sdk: `${HOST}#CredentialRecord` },
378
+ { legacy: '@deepseek-ai/dsh-credentials#ApiKeyRecord', status: 'same', sdk: `${HOST}#ApiKeyRecord` },
379
+ { legacy: '@deepseek-ai/dsh-credentials#GrantRecord', status: 'same', sdk: `${HOST}#GrantRecord` },
380
+ { legacy: '@deepseek-ai/dsh-credentials#CredentialInfo', status: 'same', sdk: `${HOST}#CredentialInfo` },
381
+ { legacy: '@deepseek-ai/dsh-credentials#ResolvedCredential', status: 'same', sdk: `${HOST}#ResolvedCredential` },
382
+ { legacy: '@deepseek-ai/dsh-credentials#CredentialRecordInfo', status: 'same', sdk: `${HOST}#CredentialRecordInfo` },
383
+ { legacy: '@deepseek-ai/dsh-credentials#CredentialRecordEntry', status: 'same', sdk: `${HOST}#CredentialRecordEntry` },
384
+ { legacy: '@deepseek-ai/dsh-credentials#CredentialProvider', status: 'changed', sdk: `${HOST}#CredentialProvider`, todo: false, note: '只有类型(`ctx.credentials` 的形状),不是可以继承的类:插件不能提供凭据服务,FtAi 的凭据由宿主保管。只拿来标类型的用法不用改' },
385
+ { legacy: '@deepseek-ai/dsh-credentials#default', status: 'removed', note: '默认导出是可以继承的 `CredentialProvider` 类,插件不能提供凭据服务。要标类型用 `import type { CredentialProvider } from \'@ftai/plugin-sdk/host\'`' },
386
+ { legacy: 'ctx.settings', status: 'changed', sdk: 'ctx.settings', note: '第三方插件的配置来源:每个插件一份 JSON 文档,在它的数据目录里,加载时按 `Config` 校验后作为 `apply` 的第二个参数。`ns` 是包名,只能是插件自己:`describe()` 只给自己,写别的 `ns` 报错。可以写全部字段(0.12 只能写 volatile 的)。密钥字段在 JSON Schema 里写 `writeOnly: true`(zod 写 `.meta({ writeOnly: true })`),`Config` 给不出 JSON Schema 时 `redactSecrets` 不给值。界面用插件自己的 remote,没有 `ctx.remote.settings`;设置页照旧写在界面一半的 `settings`' },
387
+ { legacy: 'ctx.settings.configure', status: 'changed', sdk: 'ctx.settings', note: '`auto` 的意思变了:默认改了配置就重新加载这个插件(撤销再激活);`auto: false` 不重新加载,插件听 `settings/document-updated` 读 `describe()` 自己处理。0.12 的 `auto: false` 只是不生成设置页,那样写的插件现在要自己处理配置变化。随 `owner` 撤销,`owner` 要属于这个插件' },
388
+ { legacy: 'ctx.settings.update', status: 'changed', sdk: 'ctx.settings', todo: false, note: '合并 `patch`。0.12 只能写 volatile 的字段,这里全部字段都可写(含密钥);写完默认重新加载这个插件(见 `configure`)' },
389
+ { legacy: 'ctx.settings.replace', status: 'changed', sdk: 'ctx.settings', todo: false, note: '整份替换:全部字段先回到默认值再并入 `section`,没写的字段(含密钥)也会被重置。0.12 只重置 volatile 的字段,其余保留' },
390
+ { legacy: 'ctx.settings.mutate', status: 'changed', sdk: 'ctx.settings', todo: false, note: '按路径改(`SettingsPathOp`);可写的字段同 `update`:0.12 只能改 volatile 的,这里全部字段都可改' },
391
+ { legacy: 'ctx.settings.register', status: 'removed', note: SETTINGS_BEFORE_0_1_7 },
392
+ { legacy: 'ctx.settings.get', status: 'removed', note: SETTINGS_BEFORE_0_1_7 },
393
+ { legacy: 'ctx.settings.installSection', status: 'removed', note: SETTINGS_BEFORE_0_1_7 },
394
+ { legacy: '@deepseek-ai/dsh-settings#installSettingsSection', status: 'removed', note: SETTINGS_BEFORE_0_1_7 },
395
+ { legacy: 'settings/document-updated', status: 'changed', sdk: 'settings/document-updated', note: '参数同 0.12(`ns` 是包名):配置经 `ctx.settings` 写过,或 `describe()` 发现文档被改过时发。只发给这个插件自己;运行时不监听文件。默认(`auto`)下这两种情形都会重新加载这个插件,`describe()` 发现文档被手改过时也一样' },
396
+ { legacy: 'ctx.goals', status: 'changed', sdk: 'ctx.goals', note: '方法名与错误类(`GoalError`)同 0.12,全部返回 Promise,第一个参数 `agent` 换成会话 id(`agent.id`)。与界面同一条路径:`create`、`edit`、`resume` 之后会话空闲时随即排下一轮(`create` 不给 `maxGoalRounds` 时 256 轮),`pause` 停下正在跑的这一轮,0.12 的服务不碰轮次。`create` 拒绝子 agent 的会话(`GOAL_AGENT_NOT_LIVE`);`get` 对不存在的会话是 undefined' },
397
+ { legacy: 'ctx.goals.get', status: 'changed', sdk: 'ctx.goals', awaited: 'call', note: '返回 Promise,加 `await`;第一个参数换成会话 id(`agent.id`)' },
398
+ { legacy: 'ctx.goals.create', status: 'changed', sdk: 'ctx.goals', awaited: 'call', note: '返回 Promise,加 `await`;第一个参数换成会话 id(`agent.id`)' },
399
+ { legacy: 'ctx.goals.edit', status: 'changed', sdk: 'ctx.goals', awaited: 'call', note: '返回 Promise,加 `await`;第一个参数换成会话 id(`agent.id`)' },
400
+ { legacy: 'ctx.goals.pause', status: 'changed', sdk: 'ctx.goals', awaited: 'call', note: '返回 Promise,加 `await`;第一个参数换成会话 id(`agent.id`)' },
401
+ { legacy: 'ctx.goals.resume', status: 'changed', sdk: 'ctx.goals', awaited: 'call', note: '返回 Promise,加 `await`;第一个参数换成会话 id(`agent.id`)' },
402
+ { legacy: 'ctx.goals.complete', status: 'changed', sdk: 'ctx.goals', awaited: 'call', note: '返回 Promise,加 `await`;第一个参数换成会话 id(`agent.id`)' },
403
+ { legacy: 'ctx.goals.block', status: 'changed', sdk: 'ctx.goals', awaited: 'call', note: '返回 Promise,加 `await`;第一个参数换成会话 id(`agent.id`)' },
404
+ { legacy: 'ctx.goals.clear', status: 'changed', sdk: 'ctx.goals', awaited: 'call', note: '返回 Promise,加 `await`;第一个参数换成会话 id(`agent.id`)' },
405
+ { legacy: 'ctx.goals.disarm', status: 'changed', sdk: 'ctx.goals', awaited: 'call', note: '返回 Promise,加 `await`;第一个参数换成会话 id(`agent.id`)' },
406
+ { legacy: 'goal/changed', status: 'changed', sdk: 'goal/changed', note: '载荷的 `agent` 换成 `sessionId`,`change` 同 0.12。不分 agent,不能挂在 `agent.ctx` 上,按 `sessionId` 自己过滤;单向通知,不等监听者' },
407
+ { legacy: 'goal/activation-changed', status: 'same', sdk: 'goal/activation-changed', note: '载荷同 0.12;单向通知,不等监听者' },
408
+ { legacy: 'ctx.schedule', status: 'same', sdk: 'ctx.schedule', note: '方法名、参数与结果同 0.12(本来就是异步的),输入不合规抛 `ScheduleInputError`。可以往任意会话排任务,`catalog` 能看全部会话的任务。`catalog` 的 `status` 比 0.12 多一种 `paused`(用户在界面暂停的);暂停、恢复、立即运行与转移不在 0.12 的接口里,不开放。dsh 0.2.2-rc.1 起的 `edit`、`run`、`view`、`deleteInactive`、`deliveryLimits` 与 `remote*` 不提供,`update`、`delete` 照 0.12' },
409
+ { legacy: 'schedule/changed', status: 'same', sdk: 'schedule/changed', note: '没有载荷,重新读 `ctx.schedule`;一批变化可能合成一次' },
410
+ { legacy: 'ctx.permissionPresets', status: 'changed', sdk: 'ctx.permissionPresets', note: '`names()`、`catalog()`、`defaultPreset()`、`current(sessionId)`、`resolve(name)`、`optionOf(name)`、`set(sessionId, name)`,都是 Promise,`names`、`defaultPreset` 从属性改成方法。预设是 `read-only`、`workspace-write`、`guardian`、`danger-full-access`,`guardian` 不等于 0.12 的 `auto`(工作区可写加审查)。选项的 `name` 就是预设名,没有 `description`,另有 `sandbox`、`approval`;`set` 任意会话都能收紧或切到别的预设;2.3.0 起要在 `ftai.capabilities` 里声明 `permissions.set`,切到完全访问还要声明 `permissions.full-access` 并经用户按插件授权(没授权时问用户),不允许时报 `permission/full-access-not-allowed`、会话不动,会话本来就是完全访问时照常;子 agent 的会话报 `agent/subagent-session`,下一次工具派发起生效。未知的预设报 `permission/unknown-preset`。没有 `registerAuto`:自动审批由宿主的审查者负责' },
411
+ { legacy: 'ctx.permissionPresets.catalog', status: 'changed', sdk: 'ctx.permissionPresets', awaited: 'call', note: '返回 Promise,加 `await`' },
412
+ { legacy: 'ctx.permissionPresets.resolve', status: 'changed', sdk: 'ctx.permissionPresets', awaited: 'call', note: '返回 Promise,加 `await`' },
413
+ { legacy: 'ctx.permissionPresets.optionOf', status: 'changed', sdk: 'ctx.permissionPresets', awaited: 'call', note: '返回 Promise,加 `await`' },
414
+ { legacy: 'ctx.permissionPresets.current', status: 'changed', sdk: 'ctx.permissionPresets', awaited: 'call', note: '返回 Promise,加 `await`;第一个参数换成会话 id(`agent.id`)' },
415
+ { legacy: 'ctx.permissionPresets.set', status: 'changed', sdk: 'ctx.permissionPresets', awaited: 'call', note: '返回 Promise,加 `await`;第一个参数换成会话 id(`agent.id`)' },
416
+ { legacy: 'permission-presets/catalog-changed', status: 'same', sdk: 'permission-presets/catalog-changed', note: '可以监听;预设表是写死的,现在不会触发' },
417
+ { legacy: 'ctx.planMode', status: 'pending', note: '阶段 3:读与切换会话的计划模式' },
418
+ { legacy: 'ctx.compaction', status: 'changed', sdk: 'ctx.compaction', note: '`compactNow(sessionId, signal?, sourceCommandId?)`、`compactIfNeeded(sessionId, trigger, signal?)`:第一个参数 `agent` 换成会话 id(`agent.id`),`signal` 可选,结果与 `ManualCompactionError` 同 0.12。中止时抛 `signal.reason`,已经开始的压缩收到取消,在日志里照常收尾;要再压等它放开会话。`compactRegion` 见下一行' },
419
+ { legacy: 'ctx.compaction.compactRegion', status: 'pending', note: '没有开放:宿主的压缩范围都由它自己选(`compactNow` 与 `compactIfNeeded`),还没有让调用方指定范围的入口' },
420
+ { legacy: 'compaction/summary-error', status: 'changed', sdk: 'compaction/summary-error', note: '载荷的 `session` 换成 `sessionId`,`error` 换成 `{ message, code? }`,没有 `signal`;`next()` 返回 Promise。写下改动后返回 true 重试摘要,排在图片卸载之后。每次压缩最多重试 3 次,超时(60 秒)或抛错按不重试' },
421
+ { legacy: 'ctx.mcpResources', status: 'pending', note: '阶段 3:插件提供 MCP 资源' },
422
+ { legacy: 'ctx.subagents', status: 'changed', sdk: 'ctx.subagents', note: '成员见各自一行,跨进程后都返回 Promise,收 agent 句柄的地方收会话 id。与委派工具同一条路径:深度 1、每棵委派树 8 个、审批固定为 never、沙箱照抄父会话,不给插件放宽。提供者固定为 `spawn`、`fork`。dsh 0.2.0 及更早的 `start`、`startContinuable`、`followup`、`registerContinuableSetup` 到 0.12 已换成 `startActivation` 等,这里只有 0.12 的写法' },
423
+ { legacy: 'ctx.subagents.startActivation', status: 'changed', sdk: 'ctx.subagents', note: '`request.parent` 是会话 id,可以是任意会话(包括空闲的),归档的报 `agent/session-archived`。`outputSchema` 不支持,报 `UNSUPPORTED_CAPABILITY`。`toolFilter` 只能在宿主收起的工具之外再收。`persona` 换掉身份段,回复语言规则照旧,不做 `{{变量}}` 替换。结果没有 `structured`、`diagnostic`。`dispose` 随调用方撤销;插件进程崩溃时不停子 agent' },
424
+ { legacy: 'ctx.subagents.sendMessage', status: 'changed', sdk: 'ctx.subagents', note: '`sender` 是会话 id' },
425
+ { legacy: 'ctx.subagents.interrupt', status: 'changed', sdk: 'ctx.subagents', awaited: 'call', note: '返回 Promise,加 `await`;`{ kind: \'ancestor\', agent }` 的 `agent` 是会话 id。没有权限时 Promise 拒绝' },
426
+ { legacy: 'ctx.subagents.listChildren', status: 'same', sdk: 'ctx.subagents', note: '没有这个会话时报 `agent/session-not-found`' },
427
+ { legacy: 'ctx.subagents.listDescendants', status: 'same', sdk: 'ctx.subagents', note: '`activity` 是子 agent 此刻在不在跑(0.12 是在不在内存里)' },
428
+ { legacy: 'ctx.subagents.waitForChildren', status: 'changed', sdk: 'ctx.subagents', todo: false, note: '`parent` 是会话 id' },
429
+ { legacy: 'ctx.subagents.list', status: 'changed', sdk: 'ctx.subagents', awaited: 'call', note: '返回 Promise,加 `await`:总是 `spawn`、`fork`' },
430
+ { legacy: 'ctx.subagents.registerProvider', status: 'pending', note: '阶段 3:宿主的提供者固定为 spawn、fork,插件提供者要用户定' },
431
+ { legacy: 'ctx.subagents.getProvider', status: 'pending', note: '阶段 3:宿主的提供者固定为 spawn、fork,插件提供者要用户定' },
432
+ { legacy: '@deepseek-ai/dsh-subagent#SubagentError', status: 'same', sdk: `${HOST}#SubagentError`, note: '错误码是大写的那些;会话不存在、已归档是宿主的错误码(`agent/session-not-found`、`agent/session-archived`),原样抛出' },
433
+ { legacy: '@deepseek-ai/dsh-subagent#SubagentDepthError', status: 'changed', sdk: `${HOST}#SubagentDepthError`, note: '没有 `attemptedDepth`、`maxDepth`,都在 `message` 里' },
434
+ { legacy: '@deepseek-ai/dsh-subagent#SubagentRuntime', status: 'changed', sdk: `${HOST}#SubagentRuntime`, todo: false, note: '接口,不是要继承的类;方法都返回 Promise' },
435
+ { legacy: '@deepseek-ai/dsh-subagent#SubagentActivationSpec', status: 'changed', sdk: `${HOST}#SubagentActivationSpec`, todo: false, note: '`request.parent` 是会话 id;没有 `outputSchema`' },
436
+ { legacy: '@deepseek-ai/dsh-subagent#SubagentActivation', status: 'same', sdk: `${HOST}#SubagentActivation` },
437
+ { legacy: '@deepseek-ai/dsh-subagent#SubagentResult', status: 'changed', sdk: `${HOST}#SubagentResult`, todo: false, note: '没有 `structured`、`diagnostic`' },
438
+ { legacy: '@deepseek-ai/dsh-subagent#SubagentInterruptAuthority', status: 'changed', sdk: `${HOST}#SubagentInterruptAuthority`, todo: false, note: '`agent` 是会话 id' },
439
+ { legacy: '@deepseek-ai/dsh-subagent#SubagentRunInfo', status: 'same', sdk: `${HOST}#SubagentRunInfo` },
440
+ { legacy: '@deepseek-ai/dsh-subagent#SubagentRunEndInfo', status: 'same', sdk: `${HOST}#SubagentRunEndInfo` },
441
+ { legacy: '@deepseek-ai/dsh-commands#CommandInvocation', status: 'same', sdk: `${HOST}#CommandInvocation` },
442
+ { legacy: '@deepseek-ai/dsh-commands#CommandResult', status: 'same', sdk: `${HOST}#CommandResult` },
443
+ { legacy: '@deepseek-ai/dsh-compaction#ManualCompactionError', status: 'same', sdk: `${HOST}#ManualCompactionError` },
444
+ { legacy: '@deepseek-ai/dsh-commands/brand#CommandDefinitionId', status: 'same', sdk: `${HOST}#CommandDefinitionId`, brand: true, note: '就是字符串:`CommandDefinitionId(...)` 包装由 codemod 去掉' },
445
+ { legacy: '@deepseek-ai/dsh-goal#GoalId', status: 'same', sdk: `${HOST}#GoalId`, brand: true, note: '就是字符串:`GoalId(...)` 包装由 codemod 去掉' },
446
+ { legacy: '@deepseek-ai/dsh-schedule#ScheduleId', status: 'same', sdk: `${HOST}#ScheduleId`, brand: true, note: '就是字符串:`ScheduleId(...)` 包装由 codemod 去掉' },
447
+ { legacy: '@deepseek-ai/dsh-goal#GoalError', status: 'same', sdk: `${HOST}#GoalError` },
448
+ { legacy: '@deepseek-ai/dsh-goal#GoalPhase', status: 'same', sdk: `${HOST}#GoalPhase` },
449
+ { legacy: '@deepseek-ai/dsh-goal#GoalRef', status: 'same', sdk: `${HOST}#GoalRef` },
450
+ { legacy: '@deepseek-ai/dsh-goal#GoalView', status: 'same', sdk: `${HOST}#GoalView` },
451
+ { legacy: '@deepseek-ai/dsh-jobs/view#JobChunk', status: 'same', sdk: `${HOST}#JobChunk` },
452
+ { legacy: '@deepseek-ai/dsh-jobs#JobRead', status: 'same', sdk: `${HOST}#JobRead` },
453
+ { legacy: '@deepseek-ai/dsh-schedule#AtInput', status: 'same', sdk: `${HOST}#AtInput` },
454
+ { legacy: '@deepseek-ai/dsh-schedule#CronInput', status: 'same', sdk: `${HOST}#CronInput` },
455
+ { legacy: '@deepseek-ai/dsh-schedule#DailyInput', status: 'same', sdk: `${HOST}#DailyInput` },
456
+ { legacy: '@deepseek-ai/dsh-schedule#ScheduleInputError', status: 'same', sdk: `${HOST}#ScheduleInputError` },
457
+ { legacy: '@deepseek-ai/dsh-schedule#ScheduleTimingChange', status: 'same', sdk: `${HOST}#ScheduleTimingChange` },
458
+ { legacy: '@deepseek-ai/dsh-schedule#ScheduleToolError', status: 'same', sdk: `${HOST}#ScheduleToolError` },
459
+ { legacy: '@deepseek-ai/dsh-schedule#WeeklyInput', status: 'same', sdk: `${HOST}#WeeklyInput` },
460
+ { legacy: '@deepseek-ai/dsh-session-persistence#SessionHandle', status: 'same', sdk: `${HOST}#SessionHandle` },
461
+ { legacy: '@deepseek-ai/dsh-shell#ShellExecutor', status: 'same', sdk: `${HOST}#ShellExecutor` },
462
+ { legacy: '@deepseek-ai/dsh-shell#ShellRunResult', status: 'same', sdk: `${HOST}#ShellRunResult` },
463
+ { legacy: '@deepseek-ai/dsh-skill#SkillSummary', status: 'same', sdk: `${HOST}#SkillSummary` },
464
+ { legacy: '@deepseek-ai/dsh-subprocess#SubprocessOutputRead', status: 'same', sdk: `${HOST}#SubprocessOutputRead` },
465
+ { legacy: '@deepseek-ai/dsh-user-questions/types#AskUserQuestionAnswer', status: 'same', sdk: `${HOST}#AskUserQuestionAnswer` },
466
+ { legacy: '@deepseek-ai/dsh-user-questions/types#AskUserQuestionRequestEvent', status: 'changed', sdk: `${HOST}#AskUserQuestionRequest`, todo: false, note: '收 `sessionId`,不收 `agent`' },
467
+ { legacy: '@deepseek-ai/dsh-web#WebFetchBody', status: 'same', sdk: `${HOST}#WebFetchBody` },
468
+ { legacy: '@deepseek-ai/dsh-web#WebFetchResult', status: 'same', sdk: `${HOST}#WebFetchResult` },
469
+ { legacy: '@deepseek-ai/dsh-web#WebSearchResult', status: 'same', sdk: `${HOST}#WebSearchResult` },
470
+ { legacy: '@deepseek-ai/dsh-web#WebSearchSource', status: 'same', sdk: `${HOST}#WebSearchSource` },
471
+ { legacy: 'subagent/provider-added', status: 'pending', note: '阶段 3:宿主的提供者固定为 spawn、fork,插件提供者要用户定' },
472
+ { legacy: 'subagent/provider-removed', status: 'pending', note: '阶段 3:宿主的提供者固定为 spawn、fork,插件提供者要用户定' },
473
+ { legacy: 'subagent/start', status: 'changed', sdk: 'subagent/start', todo: false, note: '观察点,异步送达,工具与插件起的都算。`local` 总是 true。只能在插件的 `ctx` 上监听(0.12 能在父 agent 的作用域上只收它的):载荷没有父会话,要过滤时读子会话头的 `parentSession`' },
474
+ { legacy: 'subagent/end', status: 'changed', sdk: 'subagent/end', todo: false, note: '观察点,异步送达,同 `subagent/start`' },
475
+ { legacy: 'ctx.workingDirectory', status: 'changed', sdk: 'ctx.workingDirectory', note: '`get`、`ensure`、`set` 全部返回 Promise,第一个参数换成会话 id(`agent.id`),可以操作任意会话;`defaultDirectory` 从属性变成方法 `defaultDirectory()`。错误带错误码:`ftai-sessions/not-live`、`ftai-sessions/invalid-directory`。没有 `workingDirectory` 这个会话投影,读目录用 `get`' },
476
+ { legacy: 'ctx.workingDirectory.get', status: 'changed', sdk: 'ctx.workingDirectory', awaited: 'call', note: '返回 Promise,加 `await`;第一个参数换成会话 id(`agent.id`)' },
477
+ { legacy: 'ctx.workspaceRegistry', status: 'changed', sdk: 'ctx.workspaceRegistry', note: '方法名与错误类同 0.12,全部返回 Promise。工作区是读到那一刻的数据(`id`、`path`、`title`、`sessionIds`、`createdAt`、`updatedAt`),不是活对象,没有 `setTitle`、`attachSession`、`insertSessionBefore`、`detachSession`、`status`。`archivedSessionIds`、`pinnedSessionIds` 从属性变成方法。`initializeDefault` 不开放:默认工作区不由插件决定' },
478
+ { legacy: 'ctx.workspaceRegistry.get', status: 'changed', sdk: 'ctx.workspaceRegistry', awaited: 'call', note: '返回 Promise,加 `await`;得到读到那一刻的数据' },
479
+ { legacy: 'ctx.workspaceRegistry.list', status: 'changed', sdk: 'ctx.workspaceRegistry', awaited: 'call', note: '返回 Promise,加 `await`;得到读到那一刻的数据' },
480
+ { legacy: 'workspace/session-activity', status: 'same', sdk: 'workspace/session-activity', note: '写法同 0.12:`({ sessionId }, next)`,把自己的工作加在 `next()` 的结果前面,非空就拒绝归档。藏不住下游报的工作;超时(60 秒)、抛错或插件进程不在时按它没有报,不挡归档' },
481
+ { legacy: 'workspace/session-stop', status: 'same', sdk: 'workspace/session-stop', note: '写法同 0.12:`({ sessionId })`,监听者同时跑,失败或超时(30 秒)只记日志,不撤销归档' },
482
+ { legacy: 'ctx.subprocess', status: 'changed', sdk: 'ctx.subprocess', todo: false, note: '`spawn`、`resolveExecutable`、`terminalEnvironment` 形状与语义同 0.12:环境清洗、进程组的宽限终止(POSIX;Windows 见 `spawn` 一行的 `taskkill`)、`waitForExit`、`collected`,进程随调用方的作用域撤销被杀掉。不是权限边界,不经沙箱与审批。没有 `spawnTerminal`,见下一行' },
483
+ { legacy: 'ctx.subprocess.spawnTerminal', status: 'pending', note: '阶段 3 不提供:插件进程没有 node-pty(原生模块要按 Electron 的 ABI 编译、随应用分发),PTY 现在只在宿主的终端插件里;普通子进程用 `ctx.subprocess.spawn`' },
484
+ { legacy: 'ctx.subprocess.spawn', status: 'changed', sdk: 'ctx.subprocess', todo: false, note: '同 0.12,差别:`stdio.control` 报错(子进程那头的 `openInheritedControlChannel` 也不提供,只有脚本运行时用它);`stdout: \'inherit\'` 接到插件进程的 stderr(stdout 是协议);环境还去掉 `FTAI_*` 与 `ELECTRON_RUN_AS_NODE`;只有进程组(Windows 是 `taskkill /T`),没有 0.12 的 systemd scope 与 Job 对象,逃出进程组的后代收不到' },
485
+ { legacy: 'ctx.sandboxPolicy', status: 'changed', sdk: 'ctx.sandboxPolicy', note: `${SANDBOX_POLICY}。dsh 0.2.2-rc.1 起的 \`additionalWritableRoots\` 不提供` },
486
+ { legacy: 'ctx.sandboxPolicy.resolve', status: 'changed', sdk: 'ctx.sandboxPolicy', awaited: 'call', note: SANDBOX_POLICY },
487
+ { legacy: 'ctx.sandboxPolicy.overrideOf', status: 'changed', sdk: 'ctx.sandboxPolicy', awaited: 'call', note: '返回 Promise,加 `await`;参数是会话 id' },
488
+ { legacy: 'ctx.workflowEngine', status: 'pending', note: SCRIPT_RUNTIME },
489
+ { legacy: 'workflow/start', status: 'pending', note: SCRIPT_RUNTIME },
490
+ { legacy: 'workflow/phase', status: 'pending', note: SCRIPT_RUNTIME },
491
+ { legacy: 'workflow/log', status: 'pending', note: SCRIPT_RUNTIME },
492
+ { legacy: 'workflow/agent-start', status: 'pending', note: SCRIPT_RUNTIME },
493
+ { legacy: 'workflow/agent-end', status: 'pending', note: SCRIPT_RUNTIME },
494
+ { legacy: 'workflow/end', status: 'pending', note: SCRIPT_RUNTIME },
495
+ // ── 入口与组合 ──
46
496
  { legacy: 'ctx.typert', status: 'changed', sdk: `${HOST}#TypertRemoteService`, note: '不再注入:服务继承 SDK 的 `TypertRemoteService` 即挂上 remote 命名空间;构建时把 `ftai-plugin-typert` 换成 `ftai-plugin-remote`,包导出 `./remote` 指向 `lib/remote.*`,不再有 `./typert`' },
497
+ { legacy: 'ctx.invocation', status: 'changed', sdk: 'ctx.invocation', note: '`@Remote` 方法里(含流式方法)读 `this.ctx.invocation`,同一条异步链路里的 `ctx.invocation` 也是它,调用外是 undefined。`{ request: { namespace, method, args }, service, signal }`:`args` 按位置(0.12 是具名对象),不含最后的 `signal`;没有 `peer`、`uplink`' },
498
+ { legacy: 'ctx.loader', status: 'changed', sdk: 'ctx.loader', note: '只有 `await ctx.loader.list()` 与 `setEnabled(name, on)`:宿主没有条目树,cordis loader 的 `entries`、`create`、`remove`、`update`、`import`、`resolve` 不提供。与插件页同一条路径:必达通道报 `always_on`,其余(别的第三方、绑定了核心插件的行)都能停能开,重启后保持。`setEnabled` 先答复再做,插件可以停自己,结果看 `list()`' },
499
+ { legacy: 'exit', status: 'changed', sdk: 'exit', note: '`ctx.on(\'exit\', (signal) => …)`,`signal` 恒为 `SIGTERM`:宿主结束插件进程之前(应用退出、装卸插件换进程)发,之后撤销各插件。监听者最多等 1 秒,撤销最多等 1.5 秒,宿主最多等 3 秒就硬杀;崩溃时送不到。收尾放进 `ctx.effect` 更合适,停用插件时也会跑' },
500
+ { legacy: 'cordis.patch.yml(覆盖与组合其他插件)', status: 'removed', note: '不读这个文件,`ftai-migrate-plugin` 删掉它。同一个包里再加载插件(`insert`)写 package.json 的 `ftai.plugins`(`entry`、`config`);覆盖其他插件的行(改配置、`disabled`)不提供;`!!js` 不提供,计算放进插件自己的代码' },
501
+ { legacy: 'dsh 命令行与 profile 入口', status: 'removed', note: `${COMMAND_LINE},插件装在数据目录的 \`profiles/<名>/plugins/\`,每次拉起一个只装这些插件的进程(docs/rust-host/cli.md 的「外部应用」)。进程的环境是调用方的,模型跑的命令却在后台服务里起、用后台服务的环境(dsh 的 profile 进程就是 agent,命令直接继承调用方的):要交给命令的变量在 \`ctx.agents.create\`、\`resume\` 时给 \`env\`` },
502
+ { legacy: '插件包 package.json 清单字段', status: 'changed', note: '`ftai-migrate-plugin` 改好:后端入口写 `ftai.host`,前端写 `ftai.client`,契约写 `ftai.contract`;同一个包里再加载的插件手工写 `ftai.plugins`;`dsh.bundle`、`platform`、`inject` 不再要;`icon` 不提供' },
47
503
  // ── 现有插件用到的其他服务 ──
48
504
  { legacy: 'ctx.ftaiAccount', status: 'changed', sdk: 'ctx.ftaiAccount', note: '内部 SDK,只给一方插件:`import type {} from \'@ftai/plugin-sdk-internal/host\'`;方法都是异步的,见下面各行;`static inject` 或 `ctx.get(\'ftaiAccount\')` 照旧' },
49
505
  { legacy: 'ctx.ftaiAccount.request', status: 'changed', sdk: 'ctx.ftaiAccount', note: '答复 `{ status, body }`(状态码与响应体原文),不是 `Response`:按 `status` 判断,`JSON.parse(body)` 取 JSON;请求体按 JSON 给 `body`,multipart 给 `form`(字段按顺序,文件的字节按 base64),不收 `FormData`;不收 `signal`,不能中途取消,超时缺省 15 秒(`timeoutMs`)' },
50
506
  { legacy: 'ctx.ftaiAccount.currentUserId', status: 'changed', sdk: 'ctx.ftaiAccount', note: '异步,自己先等启动时的登录恢复完:`await ctx.ftaiAccount.currentUserId()`' },
51
507
  { legacy: 'ctx.ftaiAccount.currentUserInternal', status: 'changed', sdk: 'ctx.ftaiAccount', note: '异步,自己先等启动时的登录恢复完:`await ctx.ftaiAccount.currentUserInternal()`' },
52
- { legacy: 'ctx.ftaiAccount.ftaiConnection', status: 'pending', note: '令牌不出宿主:登记经 FTAI 服务端转发的 MCP 服务器改用 `ctx.ftaiMcp.provideFtaiServer`,以登录身份发请求用 `ctx.ftaiAccount.request`;自己开长连接的(远程控制)由线 B 迁 remote-control 时定' },
508
+ { legacy: 'ctx.ftaiAccount.ftaiConnection', status: 'removed', note: '令牌不出宿主:登记经 FTAI 服务端转发的 MCP 服务器改用 `ctx.ftaiMcp.provideFtaiServer`,以登录身份发请求用 `ctx.ftaiAccount.request`,自己开长连接用 `ctx.ftaiNetwork.tunnel`' },
53
509
  { legacy: 'ctx.ftaiAccount.restored', status: 'removed', note: '去掉 `await account.restored`:`currentUserId()` 与 `request()` 自己等登录恢复完' },
54
510
  { legacy: 'ctx.ftaiAccount.watch', status: 'changed', sdk: 'ftai-account/subject-changed', note: '没有账号状态流:登录主体变了(登录、退出、换人、换公司)宿主发 `ftai-account/subject-changed`,监听它再 `await ctx.ftaiAccount.currentUserInternal()` 等重新取' },
55
511
  { legacy: 'ctx.ftaiAccount.wecomUserId', status: 'changed', sdk: 'ctx.ftaiAccount', note: '不收 `signal`:`await ctx.ftaiAccount.wecomUserId()`' },
@@ -61,64 +517,233 @@ export const PORTING_TABLE = [
61
517
  { legacy: 'ctx.ftaiPacks', status: 'changed', sdk: 'ctx.ftaiPacks', note: '内部 SDK,只给一方插件:`import type {} from \'@ftai/plugin-sdk-internal/host\'`;只有 `isEnabled`,见下一行;能力包的其余操作只给界面(remote 命名空间 `ftaiPacks`)' },
62
518
  { legacy: 'ctx.ftaiPacks.isEnabled', status: 'changed', sdk: 'ctx.ftaiPacks', note: '异步:`await ctx.ftaiPacks.isEnabled(id)`;还没读过能力包时为否,第一次读完会发 `ftai-packs/changed`' },
63
519
  { legacy: 'ctx.sessionPersistence', status: 'removed', note: '不再注入会话存储;导出会话日志改用内部 SDK 的 `ctx.sessionLog.read(sessionId)`(只给一方插件)' },
64
- { legacy: 'ctx.attachments', status: 'same', sdk: 'ctx.attachments', note: '只有 `saveImages`' },
65
- { legacy: 'ctx.attachments.saveImages', status: 'same', sdk: 'ctx.attachments', note: '`data` 是 `Uint8Array`;失败抛 `AttachmentError`,`isImageAdmissionError` 照旧' },
66
- { legacy: 'ctx.sandboxPolicy', status: 'removed', note: '插件不自己围沙箱:写二进制用 `ctx.fs.writeBytes`,宿主按这次工具调用所在会话的沙箱围住,越界时报 `FS_SANDBOX_DENIED`,说明就是给模型看的;工具要为写入申请提权(`sandbox_permissions`)时在定义里写 `sandboxEscalation: true`(见 `ctx.tools` 一行)' },
67
- { legacy: 'ctx.sandboxPolicy.resolve', status: 'removed', note: '插件不自己围沙箱:写二进制用 `ctx.fs.writeBytes`,宿主按这次工具调用所在会话的沙箱围住,越界时报 `FS_SANDBOX_DENIED`,说明就是给模型看的;工具要为写入申请提权(`sandbox_permissions`)时在定义里写 `sandboxEscalation: true`(见 `ctx.tools` 一行)' },
68
- { legacy: 'ctx.subprocess', status: 'removed', note: '插件进程里直接用 Node 的 `child_process`(插件进程有 Node 的全部能力,不经沙箱)' },
69
520
  { legacy: 'ctx.logger', status: 'same', sdk: 'ctx.logger', note: 'cordis 自带的日志,进宿主日志' },
70
521
  { legacy: 'ctx.effect', status: 'same', sdk: 'ctx.effect', note: 'cordis 自带' },
71
- { legacy: 'ctx.on', status: 'same', sdk: 'ctx.on', note: 'cordis 自带;宿主的扩展点经它监听' },
522
+ { legacy: 'ctx.on', status: 'same', sdk: 'ctx.on', note: 'cordis 自带;宿主的扩展点经它监听。选项多一个 `failClosed`:监听者失败时按拒绝(0.12 的行为),不写时当它没表态,见各扩展点' },
72
523
  { legacy: 'ctx.inject', status: 'same', sdk: 'ctx.inject', note: 'cordis 自带' },
73
524
  { legacy: 'ctx.get', status: 'same', sdk: 'ctx.get', note: 'cordis 自带' },
74
525
  { legacy: 'ctx.waterfall', status: 'same', sdk: 'ctx.waterfall', note: 'cordis 自带;宿主的扩展点不能从插件发起(如 `fs/write-intent`,见那一行)' },
75
- // ── 扩展点 ──
76
- { legacy: 'tools/pre-execute', status: 'changed', sdk: 'tools/pre-execute', todo: false, note: '`exec` 是工具调用的句柄(同一次调用总是同一个对象),`exec.arguments` 照 0.12 是解析后的 JSON;结论的四种 `kind` 照旧;超时或插件进程不在时按拒绝' },
77
- { legacy: 'agent/created', status: 'changed', sdk: 'agent/created', todo: false, note: '载荷是 `{ agent, source }`,`agent` 是句柄,按 agent 的注册写在 `agent.ctx` 上' },
78
- { legacy: 'agent/assistant-stream', status: 'changed', sdk: 'agent/assistant-stream', todo: false, note: '载荷是 `{ agent, frame }`,`frame.chunk` 是会话格式 v4 的 `StreamChunk`;跨进程按批送到' },
79
- { legacy: 'session/event', status: 'changed', sdk: 'session/event', todo: false, note: '参数是 `(session, event)`:会话句柄与会话文件里的 v4 行' },
80
- { legacy: 'fs/write-intent', status: 'removed', note: '插件不能发起:写二进制用 `ctx.fs.writeBytes`,宿主在写之前跑它,本轮改动记录据此先存下原文件' },
81
526
  { legacy: 'ftai-account/user-changed', status: 'same', sdk: 'ftai-account/user-changed', note: '内部 SDK,只给一方插件;参数照旧是新的用户 id,退出时为 null' },
82
527
  { legacy: 'ftai-packs/changed', status: 'same', sdk: 'ftai-packs/changed', note: '内部 SDK,只给一方插件;监听者收到的参数是 null' },
83
- { legacy: 'llm/stream', status: 'removed', note: '不再能改写模型的流式输出;只观察时用 `agent/assistant-stream`' },
84
- { legacy: 'tools/post-execute', status: 'pending', note: '线 A 工具:改写工具结果' },
85
- { legacy: 'system-prompt/assemble', status: 'removed', note: '按 agent 注册静态的提示词段(`agent.ctx.systemPrompt.section()`)' },
86
- { legacy: 'approval/request', status: 'removed', note: '插件不能替用户应答审批;要审批时在 `tools/pre-execute` 返回 `{ kind: \'ask\' }`' },
528
+ // ── 插件的 HTTP(plugin-parity.md「按移植标准还缺的」第 2、3 件)──
529
+ { legacy: 'ctx.webServer', status: 'same', sdk: 'ctx.webServer', note: WEB_SERVER },
530
+ { legacy: 'ctx.webServer.register', status: 'same', sdk: 'ctx.webServer', note: 'dsh 0.2.2-rc.1 起还能注册资源路由(`{ kind, path, resource }`,由宿主按资源答复),这里不支持,注册时抛错:路由要带 `handler`' },
531
+ { legacy: 'ctx.webServer.registerUpgrade', status: 'same', sdk: 'ctx.webServer' },
532
+ { legacy: 'ctx.webServer.registerFallback', status: 'same', sdk: 'ctx.webServer', note: 'dsh 0.2.2-rc.1 起也收资源(`{ resource }`),这里只收处理函数,给资源时注册抛错' },
533
+ { legacy: 'ctx.webServer.port', status: 'same', sdk: 'ctx.webServer', note: '对外的端口(宿主协议的端口),每次启动都可能不同,同 0.12 桌面端的 `--port 0`。dsh 0.2.1-rc.4 起类型是 `number | undefined`;这里监听失败时读取抛错' },
534
+ { legacy: 'ctx.webServer.host', status: 'same', sdk: 'ctx.webServer', note: '总是 `127.0.0.1`' },
535
+ { legacy: 'ctx.webServer.tapIndex', status: 'changed', sdk: 'ctx.webServer', todo: false, note: '同 0.12 桌面端:没有由宿主提供的首页,变换只在插件自己调用 `renderIndex`、`applyIndexTaps` 时套用' },
536
+ { legacy: 'ctx.webServer.applyIndexTaps', status: 'same', sdk: 'ctx.webServer' },
537
+ { legacy: 'ctx.webServer.collectIndexInjections', status: 'same', sdk: 'ctx.webServer', note: 'dsh 0.2.2-rc.1 起多一个 `peer` 参数,这里没有' },
538
+ { legacy: 'ctx.webServer.renderIndex', status: 'same', sdk: 'ctx.webServer', note: 'dsh 0.2.2-rc.1 起多一个 `peer` 参数,这里没有' },
539
+ { legacy: 'webserver/index-inject', status: 'changed', sdk: 'webserver/index-inject', note: '监听照旧,`collectIndexInjections()` 收得到;但这些行不进 FtAi 的页面(0.12 桌面端由页面逐行应用)。要在页面上加脚本或样式,写成界面一半(`ftai.client`),脚本照旧可以由插件的路由提供。dsh 0.2.2-rc.1 起监听者多收一个 `peer`,这里没有' },
540
+ { legacy: '@deepseek-ai/dsh-host-webserver#renderIndexInjections', status: 'same', sdk: `${HOST}#renderIndexInjections` },
541
+ { legacy: '@deepseek-ai/dsh-host-webserver#WebRoute', status: 'same', sdk: `${HOST}#WebRoute` },
542
+ { legacy: '@deepseek-ai/dsh-host-webserver#WebRouteKind', status: 'same', sdk: `${HOST}#WebRouteKind` },
543
+ { legacy: '@deepseek-ai/dsh-host-webserver#WebUpgradeRoute', status: 'same', sdk: `${HOST}#WebUpgradeRoute` },
544
+ { legacy: '@deepseek-ai/dsh-host-webserver#IndexInjection', status: 'same', sdk: `${HOST}#IndexInjection` },
545
+ { legacy: '@deepseek-ai/dsh-host-webserver#IndexInjectionPlacement', status: 'same', sdk: `${HOST}#IndexInjectionPlacement` },
546
+ { legacy: '@deepseek-ai/dsh-host-webserver#WebServer', status: 'changed', sdk: `${HOST}#WebServer`, note: '只有接口(类型):服务由插件进程提供,用 `ctx.webServer`,不能 `new` 或 `instanceof`' },
547
+ { legacy: '@deepseek-ai/dsh-host-webserver#default', status: 'removed', note: '用 `ctx.webServer`;类型是 `@ftai/plugin-sdk/host` 的 `WebServer`' },
548
+ { legacy: 'ctx.connection', status: 'same', sdk: 'ctx.connection', note: CONNECTION },
549
+ { legacy: 'ctx.connection.fetch', status: 'same', sdk: 'ctx.connection' },
550
+ { legacy: 'ctx.connection.requestRejection', status: 'same', sdk: 'ctx.connection' },
551
+ { legacy: 'ctx.connection.admit', status: 'same', sdk: 'ctx.connection' },
552
+ { legacy: 'ctx.connection.authorizeIndex', status: 'same', sdk: 'ctx.connection', note: 'FtAi 没有网页版界面:`/` 鉴权通过之后交给 `ctx.webServer` 的兜底,没有兜底时 404' },
553
+ { legacy: 'ctx.connection.authenticatedUrl', status: 'changed', sdk: 'ctx.connection', todo: false, note: '令牌与签名的密钥只在这次启动里:换到的浏览器会话重启后失效(0.12 可以跨重启)' },
554
+ { legacy: 'ctx.connection.createSharedFetchHandler', status: 'same', sdk: 'ctx.connection', note: '只认 `fetch.register` 登记的精确路由' },
555
+ { legacy: 'ctx.connection.operator', status: 'changed', sdk: 'ctx.connection', todo: false, note: '只有 `id`(`operator`)、`ctx` 与 `dispose`。dsh 0.2.1-rc.4 起没有 `operator`,换成 `browserPeer`、`createPeer`、`admitConnection`,这里不提供这三个' },
556
+ { legacy: 'ctx.connection.rpc', status: 'removed', note: '0.12 界面的 RPC 通道:FtAi 的界面一半调宿主一半写成 remote(`TypertRemoteService`,插件契约「前后端通信」)' },
557
+ { legacy: 'connection/request', status: 'same', sdk: 'connection/request' },
558
+ { legacy: '@deepseek-ai/dsh-client-connection#API_PATH', status: 'same', sdk: `${HOST}#API_PATH` },
559
+ { legacy: '@deepseek-ai/dsh-client-connection#ConnectionFetchRoute', status: 'same', sdk: `${HOST}#ConnectionFetchRoute` },
560
+ { legacy: '@deepseek-ai/dsh-client-connection#ConnectionFetchMethod', status: 'same', sdk: `${HOST}#ConnectionFetchMethod` },
561
+ { legacy: '@deepseek-ai/dsh-client-connection#ConnectionFetchHandler', status: 'same', sdk: `${HOST}#ConnectionFetchHandler` },
562
+ { legacy: '@deepseek-ai/dsh-client-connection#ConnectionRequestBodyMode', status: 'same', sdk: `${HOST}#ConnectionRequestBodyMode` },
563
+ { legacy: '@deepseek-ai/dsh-client-connection#ConnectionRequestRejection', status: 'same', sdk: `${HOST}#ConnectionRequestRejection` },
564
+ { legacy: '@deepseek-ai/dsh-client-connection#ConnectionTrustRequest', status: 'same', sdk: `${HOST}#ConnectionTrustRequest` },
565
+ { legacy: '@deepseek-ai/dsh-client-connection#ConnectionIndexRequest', status: 'same', sdk: `${HOST}#ConnectionIndexRequest` },
566
+ { legacy: '@deepseek-ai/dsh-client-connection#ConnectionIndexResponse', status: 'same', sdk: `${HOST}#ConnectionIndexResponse` },
567
+ { legacy: '@deepseek-ai/dsh-client-connection#HostConnectionFetch', status: 'same', sdk: `${HOST}#HostConnectionFetch` },
568
+ { legacy: '@deepseek-ai/dsh-client-connection#HostConnectionHandle', status: 'same', sdk: `${HOST}#HostConnection` },
569
+ { legacy: '@deepseek-ai/dsh-client-connection#PeerAdmission', status: 'same', sdk: `${HOST}#PeerAdmission` },
570
+ { legacy: '@deepseek-ai/dsh-client-connection#PeerScope', status: 'same', sdk: `${HOST}#PeerScope` },
571
+ { legacy: '@deepseek-ai/dsh-client-connection#clientRequestSchema', status: 'removed', note: '0.12 界面 RPC 的请求格式,随 `ctx.connection.rpc` 不提供' },
572
+ // ── 0.12 的数据目录根:插件改用自己的目录 ──
573
+ { legacy: 'ctx.dshHomePath', status: 'removed', note: NO_HARNESS_HOME },
574
+ { legacy: '@deepseek-ai/dsh-home-paths#dshHomePath', status: 'removed', note: NO_HARNESS_HOME },
575
+ { legacy: '@deepseek-ai/dsh-home-paths#dshCachePath', status: 'removed', note: NO_HARNESS_HOME },
576
+ { legacy: '@deepseek-ai/dsh-home-paths#resolveDshHome', status: 'removed', note: NO_HARNESS_HOME },
577
+ { legacy: '@deepseek-ai/dsh-home-paths#defaultDshHome', status: 'removed', note: NO_HARNESS_HOME },
578
+ // ── 0.12 的其余服务:没有排期 ──
579
+ { legacy: 'ctx.sessionQuery', status: 'pending', note: `${UNSCHEDULED}。读会话用 \`ctx.sessions\` 与句柄的 \`readHeader()\`、\`readEvents()\`;工作区里的会话用 \`ctx.workspaceRegistry\`` },
580
+ { legacy: 'ctx.sessionProjectionCache', status: 'pending', note: `${UNSCHEDULED}。投影用 \`ctx.sessionProjections\`,视图在插件进程里折叠` },
581
+ { legacy: 'ctx.remote', status: 'pending', note: `${UNSCHEDULED}。插件后端的服务继承 SDK 的 \`TypertRemoteService\` 即挂上 remote 命名空间;界面一半照旧用 \`ctx.remote\`` },
582
+ ...UNSCHEDULED_HOST.map((name) => ({ legacy: `ctx.${name}`, status: 'pending', note: UNSCHEDULED })),
583
+ ...UNSCHEDULED_CLIENT.map((name) => ({ legacy: `ctx.${name}`, status: 'pending', note: CLIENT_SIDE })),
584
+ ...OTHER_VERSIONS_HOST.map((name) => ({ legacy: `ctx.${name}`, status: 'pending', note: OTHER_VERSIONS })),
585
+ ...OTHER_VERSIONS_CLIENT.map((name) => ({ legacy: `ctx.${name}`, status: 'pending', note: CLIENT_SIDE })),
87
586
  // ── 包的导出 ──
88
587
  { legacy: '@deepseek-ai/cordis#Context', status: 'same', sdk: 'cordis#Context', note: '上游 cordis;模块扩充的目标随之改为 `cordis`' },
588
+ { legacy: 'ctx.root', status: 'changed', note: 'cordis 4.0.0-rc.12 的 `ctx` 上没有 `root` 属性,读取会抛错:改用 `ctx[Context.root]`(`Context` 要按值从 `cordis` 引入,不能是 `import type`)' },
89
589
  { legacy: '@deepseek-ai/dsh-tools#defineTool', status: 'same', sdk: `${HOST}#defineTool`, note: '参数与结果的类型照旧由 `parameters`、`output.schema` 推出;`output.render` 只给文本块与图片块(`ToolContent`,图片放 `ctx.attachments.saveImages` 得到的引用)' },
90
- { legacy: '@deepseek-ai/dsh-tools#ToolDefinition', status: 'changed', sdk: `${HOST}#ToolDefinition`, note: '不再有 `presentCall`、`presentResult`、`presentationMeta`、`projectContent`、`finalizeContent`、`deferLoading`、`timeoutMs`;`isConcurrencySafe` 只接受常量' },
590
+ { legacy: '@deepseek-ai/dsh-tools#ToolDefinition', status: 'changed', sdk: `${HOST}#ToolDefinition`, note: '不再有 `projectContent`、`presentationMeta`、`deferLoading`;`isConcurrencySafe`、`finalizeContent`、`presentCall`、`presentResult` 跨进程调用,都可以是异步的,宿主等它们有上限' },
591
+ { legacy: '@deepseek-ai/dsh-tools#ToolDefinition.output', status: 'changed', sdk: `${HOST}#ToolDefinition`, note: '必填,只有 `schema` 与 `render`;结果按 `schema` 校验,失败记作 `INVALID_TOOL_OUTPUT`;`presentationMeta` 不再有,用 `presentResult`' },
592
+ { legacy: '@deepseek-ai/dsh-tools#ToolDefinition.execute', status: 'changed', sdk: `${HOST}#ToolDefinition`, todo: false, note: '第二个参数是调用的句柄 `ToolRunContext`,见它的各行' },
593
+ { legacy: '@deepseek-ai/dsh-tools#ToolDefinition.projectContent', status: 'changed', sdk: `${HOST}#ToolDefinition`, note: '并入 `output.render(args, value)`,回退分支改为返回占位文本块' },
594
+ { legacy: '@deepseek-ai/dsh-tools#ToolDefinition.finalizeContent', status: 'changed', sdk: `${HOST}#ToolDefinition`, todo: false, note: '覆盖拒绝、超时、取消的结果。可以是异步的;抛错或超时(30 秒,这一轮已取消时 2 秒)时结果换成固定的失败文本,不回退到原文' },
595
+ { legacy: '@deepseek-ai/dsh-tools#ToolDefinition.timeoutMs', status: 'same', sdk: `${HOST}#ToolDefinition`, note: '到时记作 `TOOL_TIMEOUT`,`exec.signal` 随之触发;`tools/execute` 的监听者也算在内。宿主丢掉这次调用,不等工具体结束' },
596
+ { legacy: '@deepseek-ai/dsh-tools#ToolDefinition.isConcurrencySafe', status: 'changed', sdk: `${HOST}#ToolDefinition`, todo: false, note: '常量或函数都行。函数形式每次按参数跨进程问一次,超时(5 秒)、抛错、崩溃或不是 `true` 都按独占' },
597
+ { legacy: '@deepseek-ai/dsh-tools#ToolDefinition.presentCall', status: 'changed', sdk: `${HOST}#ToolDefinition`, todo: false, note: '执行时调用一次,结论记成插件记录,回放不再调用;最多等 2 秒,等不到或抛错时按默认卡片。界面现在只用 `title`,其余卡片按通用卡片显示' },
598
+ { legacy: '@deepseek-ai/dsh-tools#ToolDefinition.presentResult', status: 'changed', sdk: `${HOST}#ToolDefinition`, todo: false, note: '同 `presentCall`。界面现在只用 `title`、通用卡片的 `content` 与终端卡片的 `output`' },
91
599
  { legacy: '@deepseek-ai/dsh-tools#ToolExecution', status: 'changed', sdk: `${HOST}#ToolExecution`, note: '工具调用的句柄:`token`、`callId`、`name`、`arguments`、`agent`、`signal`;这一步用的模型在 `exec.model`(`{ provider, model }`),不再读 `agent.session.requestHeader().config`' },
92
- { legacy: '@deepseek-ai/dsh-session#appendPluginRecord', status: 'changed', sdk: `${HOST}#appendPluginRecord`, note: '返回 Promise(记录的 seq),加 `await`;兑现时本进程的会话投影已经读到它' },
600
+ { legacy: '@deepseek-ai/dsh-tools#ToolRunContext', status: 'changed', sdk: `${HOST}#ToolRunContext`, todo: false, note: '同 SDK 的 `ToolExecution`;缺的成员见 `ToolRunContext.*` 各行' },
601
+ { legacy: '@deepseek-ai/dsh-tools#ToolRunContext.token', status: 'same', sdk: `${HOST}#ToolRunContext`, note: '字符串,不是 symbol 品牌' },
602
+ { legacy: '@deepseek-ai/dsh-tools#ToolRunContext.callId', status: 'same', sdk: `${HOST}#ToolRunContext`, note: '字符串,不是品牌类型' },
603
+ { legacy: '@deepseek-ai/dsh-tools#ToolRunContext.name', status: 'same', sdk: `${HOST}#ToolRunContext` },
604
+ { legacy: '@deepseek-ai/dsh-tools#ToolRunContext.arguments', status: 'same', sdk: `${HOST}#ToolRunContext` },
605
+ { legacy: '@deepseek-ai/dsh-tools#ToolRunContext.agent', status: 'same', sdk: `${HOST}#ToolRunContext`, note: '总是有,不用判空;是 agent 的句柄' },
606
+ { legacy: '@deepseek-ai/dsh-tools#ToolRunContext.signal', status: 'same', sdk: `${HOST}#ToolRunContext` },
607
+ { legacy: '@deepseek-ai/dsh-tools#ToolRunContext.deferContext', status: 'changed', sdk: `${HOST}#ToolRunContext`, note: '`source.kind` 不能是 `user`(抛错);其余的来源写进会话时统一成 `{ kind: \'tool-jobs\', form: \'notice\', summary }`(会话格式冻结),原来的 `kind` 留在摘要里;图片与文件要在附件存储里' },
608
+ { legacy: '@deepseek-ai/dsh-tools#ToolRunContext.concludeTurn', status: 'same', sdk: `${HOST}#ToolRunContext`, note: '同 0.12:这次调用成功时,这一批结果都记下之后结束这一轮,同一条回复里的其他调用照常跑完' },
609
+ { legacy: '@deepseek-ai/dsh-tools#ToolRunContext.rootCallId', status: 'same', sdk: `${HOST}#ToolRunContext`, note: '模型发起的调用等于 `callId`,经 `ctx.tools.execute` 嵌套的调用是传的值' },
610
+ { legacy: '@deepseek-ai/dsh-tools#ToolExecutionResult', status: 'changed', sdk: `${HOST}#ToolExecutionResult`, todo: false, note: '`value` 是可选的(核心工具没有);`content` 只有文本与图片' },
611
+ { legacy: '@deepseek-ai/dsh-tools#ToolExecutionSuccess', status: 'changed', sdk: `${HOST}#ToolExecutionSuccess`, todo: false, note: '同 `ToolExecutionResult`' },
612
+ { legacy: '@deepseek-ai/dsh-tools#ToolExecutionFailure', status: 'same', sdk: `${HOST}#ToolExecutionFailure` },
613
+ { legacy: '@deepseek-ai/dsh-tools#ToolFailure', status: 'same', sdk: `${HOST}#ToolFailure` },
614
+ { legacy: '@deepseek-ai/dsh-tools#PostToolDecision', status: 'same', sdk: `${HOST}#PostToolDecision` },
615
+ { legacy: '@deepseek-ai/dsh-tools#ToolGuard', status: 'same', sdk: `${HOST}#ToolGuard`, note: '多了异步的写法' },
616
+ { legacy: '@deepseek-ai/dsh-tools#ToolExecutionInput', status: 'changed', sdk: `${HOST}#ToolExecutionInput`, note: '`agent` 必填;没有 `parent`、`schema`(脚本运行时,阶段 4)' },
617
+ { legacy: '@deepseek-ai/dsh-tools#ToolExecutionMode', status: 'same', sdk: `${HOST}#ToolExecutionMode` },
618
+ { legacy: '@deepseek-ai/dsh-tools#ToolDispatchExecution', status: 'same', sdk: `${HOST}#ToolDispatchExecution` },
619
+ { legacy: '@deepseek-ai/dsh-tools#ToolCallView', status: 'same', sdk: `${HOST}#ToolCallView` },
620
+ { legacy: '@deepseek-ai/dsh-tools#ToolResultView', status: 'same', sdk: `${HOST}#ToolResultView` },
621
+ { legacy: '@deepseek-ai/dsh-tools#ToolRunContext.schema', status: 'pending', note: SCRIPT_RUNTIME },
622
+ { legacy: '@deepseek-ai/dsh-tools#ToolRunContext.parent', status: 'pending', note: SCRIPT_RUNTIME },
623
+ { legacy: '@deepseek-ai/dsh-session#appendPluginRecord', status: 'changed', sdk: `${HOST}#appendPluginRecord`, awaited: 'call', note: '返回 Promise(记录的 seq),加 `await`;兑现时本进程的会话投影已经读到它' },
93
624
  { legacy: '@deepseek-ai/dsh-session#pluginRecordOf', status: 'same', sdk: `${HOST}#pluginRecordOf` },
94
- { legacy: '@deepseek-ai/dsh-session/types#SessionEvent', status: 'same', sdk: `${HOST}#SessionEvent`, note: '会话文件里的 v4 行' },
95
- { legacy: '@deepseek-ai/dsh-session/types#SessionId', status: 'removed', note: '会话 id 就是字符串:去掉 `SessionId(...)` 包装' },
625
+ { legacy: '@deepseek-ai/dsh-session/types#SessionEvent', status: 'same', sdk: `${HOST}#SessionEvent`, note: '会话文件里的 v4 行,按 `type` 收窄 `data`' },
626
+ { legacy: '@deepseek-ai/dsh-session/types#SessionEventMap', status: 'same', sdk: `${HOST}#SessionEventMap` },
627
+ { legacy: '@deepseek-ai/dsh-session/types#SessionEventType', status: 'same', sdk: `${HOST}#SessionEventType` },
628
+ { legacy: '@deepseek-ai/dsh-session/types#PluginRecordType', status: 'same', sdk: `${HOST}#PluginRecordType` },
629
+ { legacy: '@deepseek-ai/dsh-session/types#TurnEndReason', status: 'same', sdk: `${HOST}#TurnEndReason` },
630
+ { legacy: '@deepseek-ai/dsh-session/types#TurnEndReasonMap', status: 'same', sdk: `${HOST}#TurnEndReasonMap` },
631
+ { legacy: 'assistant/chunk', status: 'changed', sdk: 'agent/assistant-stream', note: '会话格式 v4 没有这种事件,`session/event` 收不到:边生成边读用 `agent/assistant-stream` 的 `chunk` 帧;落盘的结果看 `assistant/message`' },
632
+ { legacy: '@deepseek-ai/dsh-llm#TokenUsage', status: 'same', sdk: `${HOST}#TokenUsage` },
633
+ { legacy: '@deepseek-ai/dsh-llm#LlmFailure', status: 'same', sdk: `${HOST}#LlmFailure` },
634
+ { legacy: '@deepseek-ai/dsh-llm#ReasoningEffortId', status: 'same', sdk: `${HOST}#ReasoningEffortId`, brand: true, note: '就是字符串:`ReasoningEffortId(...)` 包装由 codemod 去掉' },
635
+ { legacy: '@deepseek-ai/dsh-llm#SystemMessage', status: 'same', sdk: `${HOST}#SystemMessage` },
636
+ { legacy: '@deepseek-ai/dsh-llm#AssistantMessage', status: 'same', sdk: `${HOST}#AssistantMessage` },
637
+ { legacy: '@deepseek-ai/dsh-llm#ToolResultMessage', status: 'same', sdk: `${HOST}#ToolResultMessage` },
638
+ { legacy: '@deepseek-ai/dsh-llm#AssistantStreamRecord', status: 'same', sdk: `${HOST}#AssistantStreamRecord` },
639
+ { legacy: '@deepseek-ai/dsh-agent#installModelSelection', status: 'removed', note: '一个 agent 的模型由 `ctx.agents.create`、`resume` 的 `agentOptions` 定,去掉这个调用;中途要换用 `agent/request`' },
640
+ { legacy: '@deepseek-ai/dsh-agent#ModelSelectionRef', status: 'removed', note: '用 `agentOptions`,见 `installModelSelection` 一行' },
641
+ { legacy: '@deepseek-ai/dsh-agent#ModelSelection', status: 'removed', note: '用 `AgentOptions`,见 `installModelSelection` 一行' },
642
+ { legacy: '@deepseek-ai/dsh-cmdline#parseCmdline', status: 'same', sdk: `${HOST}#parseCmdline`, note: `插件带自己的 commander。${COMMAND_LINE}` },
643
+ { legacy: '@deepseek-ai/dsh-cmdline#exitOnStdinEnd', status: 'same', sdk: `${HOST}#exitOnStdinEnd`, note: '`ftai app` 把它的 stdin、stdout 接给插件,`process.stdin`、`process.stdout` 照用;`console.log` 走 stderr,不混进应用的协议' },
644
+ { legacy: 'ctx.cmdlineArgs', status: 'same', sdk: 'ctx.cmdlineArgs', note: `应用自己启动时是空列表。${COMMAND_LINE}` },
645
+ { legacy: 'ctx.appExit', status: 'changed', sdk: 'ctx.appExit', note: '只有 `ftai app` 起的才退出;在用户的应用里只记日志,不关应用' },
646
+ { legacy: 'ctx.appReady', status: 'changed', sdk: 'ctx.appReady', note: '`ftai app` 起时要全部插件加载起来才跑;用户的应用里一个第三方插件失败不影响别的插件,照样跑' },
647
+ { legacy: '@deepseek-ai/dsh-session/types#SessionId', status: 'same', sdk: `${HOST}#SessionId`, brand: true, note: '就是字符串:`SessionId(...)` 包装由 codemod 去掉' },
648
+ { legacy: '@deepseek-ai/dsh-session/types#SessionHeader', status: 'changed', sdk: `${HOST}#SessionHeader`, note: '投影的 `init` 与句柄的 `header` 只有 `cwd`;完整的会话头是 `SessionLogHeader`,用 `await session.readHeader()` 读' },
96
649
  { legacy: '@deepseek-ai/dsh-session/types#PluginRecordMap', status: 'same', sdk: `${HOST}#PluginRecordMap`, note: '模块扩充的目标改为 `@ftai/plugin-sdk/host`' },
650
+ { legacy: '@deepseek-ai/dsh-session-projection/types#SessionProjectionMap', status: 'same', sdk: `${HOST}#SessionProjectionMap`, note: '模块扩充的目标改为 `@ftai/plugin-sdk/host`;视图经插件自己的 remote 交给界面' },
97
651
  { legacy: '@deepseek-ai/dsh-session-projection/types#SessionProjectionStateMap', status: 'same', sdk: `${HOST}#SessionProjectionStateMap`, note: '模块扩充的目标改为 `@ftai/plugin-sdk/host`' },
98
652
  { legacy: '@deepseek-ai/dsh-session-log-export#flushLiveSessionLog', status: 'removed', note: '去掉:宿主的会话写入同步落盘,`ctx.sessionLog.read()` 读到的已包含刚发生的事件' },
99
653
  { legacy: '@deepseek-ai/dsh-session-log-export#readSessionLogText', status: 'changed', sdk: 'ctx.sessionLog', note: '内部 SDK,只给一方插件:`await ctx.sessionLog.read(sessionId)`,参数是会话 id 字符串,没有这个会话时为 null(不是 undefined)' },
100
654
  { legacy: '@deepseek-ai/dsh-typert-protocol#TypertRemoteService', status: 'same', sdk: `${HOST}#TypertRemoteService`, note: '服务名就是 remote 命名空间;服务类要从包的入口导出(`ftai-plugin-remote` 引用它生成前端的类型)' },
101
- { legacy: '@deepseek-ai/dsh-typert-protocol#Remote', status: 'same', sdk: `${HOST}#Remote`, note: '`@Remote`、`@Remote(\'名字\')`、`@Remote({ mode: \'stream\' })` 照旧;宿主另传最后一个参数 `signal`' },
655
+ { legacy: '@deepseek-ai/dsh-typert-protocol#Remote', status: 'same', sdk: `${HOST}#Remote`, note: '`@Remote`、`@Remote(\'名字\')`、`@Remote({ mode: \'stream\' })` 照旧;宿主另传最后一个参数 `signal`。dsh 0.2.1-rc.4 起的 `@Remote({ name, mode })` 照旧,`name` 是调用名;`resources` 不支持,写了生成 remote 产物(`ftai-plugin-remote`)与加载时都报错' },
102
656
  { legacy: '@deepseek-ai/dsh-typert-protocol#RemoteError', status: 'same', sdk: `${HOST}#RemoteError`, note: '错误码登记在 `@ftai/plugin-sdk/host` 的 `RemoteErrorDetailsMap`;插件前端的结果类型(`@ftai/plugin-sdk/remote`)沿用同一张表,不用另行扩充' },
103
657
  { legacy: '@deepseek-ai/dsh-typert-protocol#RemoteScope', status: 'removed', note: '与会话相关的方法直接收 `sessionId` 字符串' },
104
- { legacy: '@deepseek-ai/dsh-llm#BlockAssembler', status: 'changed', sdk: `${HOST}#BlockAssembler`, note: '拼法同 0.12(单测逐项比对);没有 `replayState` 与 `message()`' },
658
+ { legacy: '@deepseek-ai/dsh-llm#BlockAssembler', status: 'changed', sdk: `${HOST}#BlockAssembler`, note: '拼法同 0.12(单测逐项比对);`message()` 给的是可以放回 `messages` 的回复,没有 `id`' },
105
659
  { legacy: '@deepseek-ai/dsh-llm#ContentBlock', status: 'changed', sdk: `${HOST}#ContentBlock`, note: '只有文本、推理、图片、文件与工具调用块(没有工具增减块);图片块没有 `offloaded`' },
106
- { legacy: '@deepseek-ai/dsh-llm#GenerateOptions', status: 'changed', sdk: `${HOST}#GenerateOptions`, note: '只收 `provider`、`model`、`system`、`messages`、`maxTokens`、`reasoningEffort`、`sessionId` 与 `signal`;`messages` 只有 user 与 assistant 两种' },
107
- { legacy: '@deepseek-ai/dsh-llm#StreamChunk', status: 'changed', sdk: `${HOST}#StreamChunk`, note: '同会话格式 v4 的 `StreamChunk`,`finish` 不带 `replayState`;`agent/assistant-stream` 的一帧是 `StreamFrame`,其中的 `chunk` 也是它(类型是 JSON 对象)' },
660
+ { legacy: '@deepseek-ai/dsh-llm#GenerateOptions', status: 'changed', sdk: `${HOST}#GenerateOptions`, note: '没有 `toolHistory`(路由都按完整声明发);`messages` 没有 developer;工具声明没有 `deferLoading`。`llm/stream` 的监听者收的是 `LlmStreamOptions`,不要标成这个类型' },
661
+ { legacy: '@deepseek-ai/dsh-llm#StreamChunk', status: 'changed', sdk: `${HOST}#StreamChunk`, note: '同会话格式 v4 的 `StreamChunk`;`agent/assistant-stream` 的一帧是 `StreamFrame`,其中的 `chunk` 也是它(类型是 JSON 对象),没有监听者与适配器时 `finish` 不带 `replayState`' },
108
662
  { legacy: '@deepseek-ai/dsh-fs#FsError', status: 'same', sdk: `${HOST}#FsError`, note: '错误码同 0.12(`FS_TOO_LARGE` 等),`instanceof FsError` 照旧' },
109
663
  { legacy: '@deepseek-ai/dsh-fs#FsTarget', status: 'same', sdk: `${HOST}#FsTarget`, note: '`targetKey` 是普通字符串,不是品牌类型' },
110
664
  { legacy: '@deepseek-ai/dsh-attachment#ImageAttachmentRef', status: 'same', sdk: `${HOST}#ImageAttachmentRef`, note: '`attachmentId` 是普通字符串,不是品牌类型' },
111
- { legacy: '@deepseek-ai/dsh-sandbox#SandboxExecutionPolicy', status: 'removed', note: '插件不自己围沙箱:写二进制用 `ctx.fs.writeBytes`,宿主按这次工具调用所在会话的沙箱围住,越界时报 `FS_SANDBOX_DENIED`,说明就是给模型看的;工具要为写入申请提权(`sandbox_permissions`)时在定义里写 `sandboxEscalation: true`(见 `ctx.tools` 一行)' },
112
- { legacy: '@deepseek-ai/dsh-sandbox#SandboxMode', status: 'removed', note: '插件不自己围沙箱:写二进制用 `ctx.fs.writeBytes`,宿主按这次工具调用所在会话的沙箱围住,越界时报 `FS_SANDBOX_DENIED`,说明就是给模型看的;工具要为写入申请提权(`sandbox_permissions`)时在定义里写 `sandboxEscalation: true`(见 `ctx.tools` 一行)' },
113
- { legacy: '@deepseek-ai/dsh-sandbox#ESCALATION_TARGETS', status: 'removed', note: '插件不自己围沙箱:写二进制用 `ctx.fs.writeBytes`,宿主按这次工具调用所在会话的沙箱围住,越界时报 `FS_SANDBOX_DENIED`,说明就是给模型看的;工具要为写入申请提权(`sandbox_permissions`)时在定义里写 `sandboxEscalation: true`(见 `ctx.tools` 一行)' },
114
- { legacy: '@deepseek-ai/dsh-sandbox#approveEscalation', status: 'removed', note: '插件不自己围沙箱:写二进制用 `ctx.fs.writeBytes`,宿主按这次工具调用所在会话的沙箱围住,越界时报 `FS_SANDBOX_DENIED`,说明就是给模型看的;工具要为写入申请提权(`sandbox_permissions`)时在定义里写 `sandboxEscalation: true`(见 `ctx.tools` 一行)' },
115
- { legacy: '@deepseek-ai/dsh-sandbox#escalationHintMarker', status: 'removed', note: '插件不自己围沙箱:写二进制用 `ctx.fs.writeBytes`,宿主按这次工具调用所在会话的沙箱围住,越界时报 `FS_SANDBOX_DENIED`,说明就是给模型看的;工具要为写入申请提权(`sandbox_permissions`)时在定义里写 `sandboxEscalation: true`(见 `ctx.tools` 一行)' },
116
- { legacy: '@deepseek-ai/dsh-sandbox#sandboxDenialMarker', status: 'removed', note: '插件不自己围沙箱:写二进制用 `ctx.fs.writeBytes`,宿主按这次工具调用所在会话的沙箱围住,越界时报 `FS_SANDBOX_DENIED`,说明就是给模型看的;工具要为写入申请提权(`sandbox_permissions`)时在定义里写 `sandboxEscalation: true`(见 `ctx.tools` 一行)' },
117
- { legacy: '@deepseek-ai/dsh-sandbox#sandboxPermissionsDescription', status: 'removed', note: '插件不自己围沙箱:写二进制用 `ctx.fs.writeBytes`,宿主按这次工具调用所在会话的沙箱围住,越界时报 `FS_SANDBOX_DENIED`,说明就是给模型看的;工具要为写入申请提权(`sandbox_permissions`)时在定义里写 `sandboxEscalation: true`(见 `ctx.tools` 一行)' },
118
- { legacy: '@deepseek-ai/dsh-sandbox#validateEscalationArgs', status: 'removed', note: '插件不自己围沙箱:写二进制用 `ctx.fs.writeBytes`,宿主按这次工具调用所在会话的沙箱围住,越界时报 `FS_SANDBOX_DENIED`,说明就是给模型看的;工具要为写入申请提权(`sandbox_permissions`)时在定义里写 `sandboxEscalation: true`(见 `ctx.tools` 一行)' },
119
- { legacy: '@deepseek-ai/dsh-sandbox#writableRoots', status: 'removed', note: '插件不自己围沙箱:写二进制用 `ctx.fs.writeBytes`,宿主按这次工具调用所在会话的沙箱围住,越界时报 `FS_SANDBOX_DENIED`,说明就是给模型看的;工具要为写入申请提权(`sandbox_permissions`)时在定义里写 `sandboxEscalation: true`(见 `ctx.tools` 一行)' },
120
- { legacy: '@deepseek-ai/dsh-sandbox-policy#SandboxPolicyService', status: 'removed', note: '插件不自己围沙箱:写二进制用 `ctx.fs.writeBytes`,宿主按这次工具调用所在会话的沙箱围住,越界时报 `FS_SANDBOX_DENIED`,说明就是给模型看的;工具要为写入申请提权(`sandbox_permissions`)时在定义里写 `sandboxEscalation: true`(见 `ctx.tools` 一行)' },
121
- { legacy: '@deepseek-ai/schemastery#default', status: 'removed', note: '插件配置的 schema 改用 standard schema 的库(如 zod),写在插件的 `Config` 上;cordis 在组合时校验' },
665
+ { legacy: '@deepseek-ai/dsh-sandbox#SandboxExecutionPolicy', status: 'same', sdk: `${HOST}#SandboxExecutionPolicy`, note: '`ctx.sandboxPolicy.resolve()` 的结果;要写文件仍用 `ctx.fs.writeBytes`,由宿主围住' },
666
+ { legacy: '@deepseek-ai/dsh-sandbox#SandboxMode', status: 'same', sdk: `${HOST}#SandboxMode` },
667
+ { legacy: '@deepseek-ai/dsh-sandbox#SANDBOX_UNAVAILABLE', status: 'same', sdk: `${HOST}#SANDBOX_UNAVAILABLE` },
668
+ { legacy: '@deepseek-ai/dsh-sandbox#SandboxUnavailableError', status: 'changed', sdk: `${HOST}#SandboxUnavailableError`, note: '由宿主抛出;构造参数是说明文字,不是 `(mode, detail)`' },
669
+ { legacy: '@deepseek-ai/dsh-sandbox#ESCALATION_TARGETS', status: 'removed', note: NO_SANDBOX },
670
+ { legacy: '@deepseek-ai/dsh-sandbox#approveEscalation', status: 'removed', note: NO_SANDBOX },
671
+ { legacy: '@deepseek-ai/dsh-sandbox#escalationHintMarker', status: 'removed', note: NO_SANDBOX },
672
+ { legacy: '@deepseek-ai/dsh-sandbox#sandboxDenialMarker', status: 'removed', note: NO_SANDBOX },
673
+ { legacy: '@deepseek-ai/dsh-sandbox#sandboxPermissionsDescription', status: 'removed', note: NO_SANDBOX },
674
+ { legacy: '@deepseek-ai/dsh-sandbox#validateEscalationArgs', status: 'removed', note: NO_SANDBOX },
675
+ { legacy: '@deepseek-ai/dsh-sandbox#writableRoots', status: 'removed', note: NO_SANDBOX },
676
+ { legacy: '@deepseek-ai/dsh-sandbox-policy#SandboxPolicyService', status: 'changed', sdk: `${HOST}#SandboxPolicyService`, note: SANDBOX_POLICY },
677
+ { legacy: '@deepseek-ai/schemastery#default', status: 'same', sdk: '@deepseek-ai/schemastery#default', note: 'import 不用改:插件自己没装这个包时,插件进程用自带的一份(3.18.5,同 0.12.5 的 3.18.5-alpha.1 一代)。cordis 经 standard schema 的 `~standard` 校验 `Config`。第三方插件的配置来自它的配置文档(`ctx.settings`),文档不存在时按 `{}` 校验:没有默认值的字段要先写进文档,否则加载失败;`ctx.settings.describe()` 的 `schema` 是 JSON Schema,schemastery 写的 `Config` 投不出,不给这个字段' },
678
+ // 真实验收查出:下面这些 SDK 都有,表里没有时 codemod 会错报「不提供」
679
+ { legacy: '@deepseek-ai/dsh-llm#LlmError', status: 'same', sdk: `${HOST}#LlmError` },
680
+ { legacy: '@deepseek-ai/dsh-llm#RequestMessage', status: 'changed', sdk: `${HOST}#RequestMessage`, note: '`source` 可能没有:协议层用不到的请求消息不带它' },
681
+ { legacy: '@deepseek-ai/cordis#FiberState', status: 'changed', sdk: `${HOST}#FiberState`, note: '从 `@ftai/plugin-sdk/host` 引入:上游是 `const enum`,`verbatimModuleSyntax` 下直接用报 TS2748' },
682
+ { legacy: 'loader/volatile-update', status: 'changed', sdk: 'settings/document-updated', note: 'schemastery 的 `.volatile()` 字段照旧可以 `.get()`,但配置改了就整个插件重新加载、不就地换值,也不发这个事件。不想重新加载:`ctx.settings.configure({ auto: false })`,在 `settings/document-updated` 里 `ctx.settings.describe()` 读新值' },
683
+ { legacy: '@deepseek-ai/dsh-llm#ImageBlock', status: 'same', sdk: `${HOST}#ImageBlock` },
684
+ { legacy: '@deepseek-ai/dsh-llm#FinishReason', status: 'same', sdk: `${HOST}#FinishReason` },
685
+ { legacy: '@deepseek-ai/dsh-llm#ToolSchema', status: 'same', sdk: `${HOST}#ToolSchema` },
686
+ { legacy: '@deepseek-ai/dsh-llm#LlmModelInfo', status: 'same', sdk: `${HOST}#LlmModelInfo` },
687
+ { legacy: '@deepseek-ai/dsh-llm#LlmResolvedModelInfo', status: 'same', sdk: `${HOST}#LlmResolvedModelInfo` },
688
+ { legacy: '@deepseek-ai/dsh-llm#MessageSource', status: 'same', sdk: `${HOST}#MessageSource` },
689
+ { legacy: '@deepseek-ai/dsh-llm#MessageSourceMap', status: 'same', sdk: `${HOST}#MessageSourceMap` },
690
+ { legacy: '@deepseek-ai/dsh-llm#ContextFormed', status: 'same', sdk: `${HOST}#ContextFormed` },
691
+ { legacy: '@deepseek-ai/dsh-llm#Message', status: 'same', sdk: `${HOST}#SessionMessage` },
692
+ { legacy: '@deepseek-ai/dsh-tools#GenericCallView', status: 'same', sdk: `${HOST}#GenericCallView` },
693
+ { legacy: '@deepseek-ai/dsh-tools#DiffCallView', status: 'same', sdk: `${HOST}#DiffCallView` },
694
+ { legacy: '@deepseek-ai/dsh-tools#DiffResultView', status: 'same', sdk: `${HOST}#DiffResultView` },
695
+ { legacy: '@deepseek-ai/dsh-tools#FileDiff', status: 'same', sdk: `${HOST}#FileDiff` },
696
+ { legacy: '@deepseek-ai/dsh-tools#ReadResultView', status: 'same', sdk: `${HOST}#ReadResultView` },
697
+ { legacy: '@deepseek-ai/dsh-tools#SearchResultView', status: 'same', sdk: `${HOST}#SearchResultView` },
698
+ { legacy: '@deepseek-ai/dsh-tools#SearchFileMatches', status: 'same', sdk: `${HOST}#SearchFileMatches` },
699
+ { legacy: '@deepseek-ai/dsh-tools#SearchLineMatch', status: 'same', sdk: `${HOST}#SearchLineMatch` },
700
+ { legacy: '@deepseek-ai/dsh-tools#WebSearchResultView', status: 'same', sdk: `${HOST}#WebSearchResultView` },
701
+ { legacy: '@deepseek-ai/dsh-tools#WebFetchResultView', status: 'same', sdk: `${HOST}#WebFetchResultView` },
702
+ { legacy: '@deepseek-ai/dsh-tools#WebSource', status: 'same', sdk: `${HOST}#WebSource` },
703
+ { legacy: '@deepseek-ai/dsh-tools#PreToolDecision', status: 'same', sdk: `${HOST}#PreToolDecision` },
704
+ { legacy: '@deepseek-ai/dsh-util-values#JsonValue', status: 'same', sdk: `${HOST}#JsonValue` },
705
+ { legacy: '@deepseek-ai/dsh-session#UserMessage', status: 'same', sdk: `${HOST}#UserMessage` },
706
+ { legacy: '@deepseek-ai/dsh-session#SessionMessageProjection', status: 'same', sdk: `${HOST}#SessionMessageProjection` },
707
+ { legacy: '@deepseek-ai/dsh-session#Session', status: 'changed', sdk: `${HOST}#SessionHandle`, note: '`SessionHandle`:读取都是异步的(`readHeader`、`readEvents`、`readSeq`、`readSurface`),写入只收 `plugin:*`(见各 `Session.*` 行)' },
708
+ { legacy: '@deepseek-ai/dsh-session#SessionSeq', status: 'same', sdk: `${HOST}#SessionSeq`, brand: true, note: '就是数字:`SessionSeq(...)` 包装由 codemod 去掉' },
709
+ { legacy: '@deepseek-ai/dsh-session#OptionalSessionSeq', status: 'same', sdk: `${HOST}#OptionalSessionSeq` },
710
+ { legacy: '@deepseek-ai/dsh-attachment#ImageMediaType', status: 'same', sdk: `${HOST}#ImageMediaType` },
711
+ { legacy: '@deepseek-ai/dsh-attachment#ImageRequestTarget', status: 'same', sdk: `${HOST}#ImageRequestTarget` },
712
+ { legacy: '@deepseek-ai/dsh-attachment#RequestImageAttachment', status: 'same', sdk: `${HOST}#RequestImageAttachment` },
713
+ { legacy: '@deepseek-ai/dsh-attachment#FileAttachmentRef', status: 'same', sdk: `${HOST}#FileAttachmentRef` },
714
+ { legacy: '@deepseek-ai/dsh-attachment#AttachmentError', status: 'same', sdk: `${HOST}#AttachmentError` },
715
+ { legacy: '@deepseek-ai/dsh-session-projection#ProjectionDefinition', status: 'same', sdk: `${HOST}#ProjectionDefinition` },
716
+ { legacy: '@deepseek-ai/dsh-session-projection#ProjectionSnapshot', status: 'same', sdk: `${HOST}#ProjectionSnapshot` },
717
+ { legacy: '@deepseek-ai/dsh-session-projection#ProjectionCheckpoint', status: 'same', sdk: `${HOST}#ProjectionCheckpoint` },
718
+ { legacy: '@deepseek-ai/dsh-fs#FsInfo', status: 'same', sdk: `${HOST}#FsInfo` },
719
+ { legacy: '@deepseek-ai/dsh-fs#FsPathInfo', status: 'same', sdk: `${HOST}#FsPathInfo` },
720
+ { legacy: '@deepseek-ai/dsh-fs#FsDirEntry', status: 'same', sdk: `${HOST}#FsDirEntry` },
721
+ { legacy: '@deepseek-ai/dsh-fs#FsObservation', status: 'same', sdk: `${HOST}#FsObservation` },
722
+ { legacy: '@deepseek-ai/dsh-fs#FsWriteIntent', status: 'same', sdk: `${HOST}#FsWriteIntent` },
723
+ { legacy: '@deepseek-ai/dsh-fs#FsVersion', status: 'same', sdk: `${HOST}#FsVersion` },
724
+ { legacy: '@deepseek-ai/dsh-agent#TurnBoundaryProjection', status: 'same', sdk: `${HOST}#TurnBoundaryProjection` },
725
+ // 插件自己的数据与进程
726
+ { legacy: '@deepseek-ai/dsh-storage#StorageError', status: 'same', sdk: `${HOST}#StorageError`, note: '只有 `version-mismatch`、`malformed-medium`、`closed`:后端与挂载不开放' },
727
+ { legacy: '@deepseek-ai/dsh-storage-domain#defineDomain', status: 'same', sdk: `${HOST}#defineDomain`, note: '名字只在插件自己的目录里生效,不用避开核心的域' },
728
+ { legacy: '@deepseek-ai/dsh-storage-domain#domainTable', status: 'same', sdk: `${HOST}#domainTable`, note: '记录的 schema 同 0.12 写 zod;SDK 不依赖 zod,形状有 `parse`、`safeParse` 即可' },
729
+ { legacy: '@deepseek-ai/dsh-storage-domain#DomainError', status: 'same', sdk: `${HOST}#DomainError`, note: '`facet-unsupported` 不再有' },
730
+ { legacy: '@deepseek-ai/dsh-storage-domain#Domain', status: 'same', sdk: `${HOST}#Domain` },
731
+ { legacy: '@deepseek-ai/dsh-storage-domain#DomainSpec', status: 'same', sdk: `${HOST}#DomainSpec` },
732
+ { legacy: '@deepseek-ai/dsh-storage-domain#DomainChanged', status: 'same', sdk: `${HOST}#DomainChanged` },
733
+ { legacy: '@deepseek-ai/dsh-storage-domain#KvTable', status: 'same', sdk: `${HOST}#KvTable` },
734
+ { legacy: '@deepseek-ai/dsh-storage-domain#DomainGlobal', status: 'same', sdk: `${HOST}#DomainGlobal` },
735
+ { legacy: '@deepseek-ai/dsh-settings#SettingsConflictError', status: 'same', sdk: `${HOST}#SettingsConflictError` },
736
+ { legacy: '@deepseek-ai/dsh-settings#SettingsDescriptor', status: 'same', sdk: `${HOST}#SettingsDescriptor`, note: '`schema` 是 JSON Schema(0.12 是 schemastery 的 JSON),`autoGenerate` 同 `configure` 的 `auto`' },
737
+ { legacy: '@deepseek-ai/dsh-settings#SettingsPathOp', status: 'same', sdk: `${HOST}#SettingsPathOp` },
738
+ { legacy: '@deepseek-ai/dsh-settings#redactSecrets', status: 'removed', note: '用 `ctx.settings.describe({ redactSecrets: true })`' },
739
+ { legacy: '@deepseek-ai/dsh-subprocess#SubprocessHandle', status: 'changed', sdk: `${HOST}#SubprocessHandle`, todo: false, note: '没有 `control`' },
740
+ { legacy: '@deepseek-ai/dsh-subprocess#SubprocessSpawnSpec', status: 'same', sdk: `${HOST}#SubprocessSpawnSpec` },
741
+ { legacy: '@deepseek-ai/dsh-subprocess#SubprocessOutcome', status: 'same', sdk: `${HOST}#SubprocessOutcome` },
742
+ { legacy: '@deepseek-ai/dsh-subprocess#SubprocessCollect', status: 'same', sdk: `${HOST}#SubprocessCollect` },
743
+ { legacy: '@deepseek-ai/dsh-subprocess#SubprocessExecutableNotFoundError', status: 'same', sdk: `${HOST}#SubprocessExecutableNotFoundError` },
744
+ { legacy: '@deepseek-ai/dsh-subprocess#scrubbedParentEnv', status: 'removed', note: '`ctx.subprocess.spawn` 自己清洗环境;自己用 `child_process` 起的进程自己处理' },
745
+ { legacy: '@deepseek-ai/dsh-subprocess/control#openInheritedControlChannel', status: 'removed', note: '没有控制通道,见 `ctx.subprocess.spawn` 一行' },
746
+ { legacy: '@deepseek-ai/dsh-typert-protocol#RemoteInvocation', status: 'changed', sdk: `${HOST}#RemoteCallInvocation`, todo: false, note: '改名 `RemoteCallInvocation`,codemod 连引用一起改(`RemoteInvocation` 是宿主协议上的载荷);形状见 `ctx.invocation` 一行' },
122
747
  ];
123
748
  /** 按 0.12 一侧的名字查一行。 */
124
749
  export function portingOf(legacy) {