@shendeguize/dsh-agent-sidecar

dsh plugin --profile web add @shendeguize/dsh-agent-sidecar

@shendeguize/dsh-agent-sidecar

[Agent Sidecar](../README.md) 的原生 dsh 插件:在 dsh Web 的 Agent Center 中跨 agent 监控本机 AI agent 会话——看板、会话详情时间线、消息注入(默认关)、AI 旁路分析(默认关)、skill 内嵌提供,以及对 sidecar daemon 的自动托管。

能力(当前已交付,M1-M3 + skill/sidebar)

• 一等 Agent Center overlay:通过 dsh 官方 shell.overlay 注册 agent-sidecar-center(order: 30),由可观察导航状态驱动官方 Modal 内的大尺寸中心。dsh 主侧栏入口、footer 状态小件与 /sidecar 的 Agent Center 动作共享此入口,空白会话和窄屏下也可打开;会话区「Sidecar」Tab 保留为第二入口。嵌套 Modal 会把每个下层 dialog 同时标为 inert 与 aria-hidden,逐层关闭或卸载时精确恢复此前的宿主属性和焦点。
• 跨 agent 会话看板:Agent Center overlay 与会话区「Sidecar」Tab 展示本机受支持 agent(cursor IDE/CLI、claude、codex、copilot、dsh、kimi)的会话卡片与状态徽标(working / waiting / idle / dead;状态为从持久化数据推断的观察值,可能滞后),并可按 agent 类型过滤。首个快照前显示本地化 loading 且根节点为 aria-busy;首载失败结束 busy 并允许手动重试,后续刷新或流失败则保留最后成功快照并如实提示 stale/degraded 状态。
• 会话详情视图:统一时间线(融合 sidecar 规范化事件与 dsh 进程内实时事件,分页回溯历史,事件缺口如实标注,并公开不含正文的来源结果/降级状态);dsh 会话专属谱系树与全文检索(经 sessionQuery,该服务缺席时优雅降级——检索退化为标题/项目过滤,谱系显示不可用提示);项目分组视图(同一项目下跨 agent 会话并排呈现)。从看板/项目进入详情时焦点移入详情控件;返回时按 agent+session 组合身份恢复精确来源及各视图独立的有界滚动位置,来源消失或被过滤时回退到视图标题。详情内跳转到另一会话会清除原来源身份,返回时同样走标题 fallback。
• 消息注入(默认关):inject.enabled 是独立全局门,会话是否可注入另由 host 按目标派生。普通外部 agent 仅允许本机顶层 claude/codex/cursor-cli 的 waiting/idle 会话;Kimi Code 仅允许经 0.38.0/0.39.1 ACP 受保护 spawn-resume 的本机顶层 waiting/idle 会话。插件始终经 agent-sidecar send <full-session-id> --agent <agent> --exact-session --message-stdin --allow-write --json 执行；消息不进入 Sidecar 自身 argv，但 Copilot 的上游恢复合同会让消息进入其子进程 argv。Kimi 提示词只进入 ACP NDJSON 而不进入 Kimi argv。本机 DSH working 可走进程内 steer,waiting/idle 进入 live/cold 预检。unsupported/remote/dead/invalid 目标置灰并显示可访问原因。delivery: unknown 不提供重试按钮。
• AI 旁路分析(默认关):analysis.enabled 开启后,可对被观测会话/项目拉起专用 dsh 分析会话(有界摘要注入 + 增量追问 + 随时停止);模型路由见配置表 analysis.provider / analysis.model。分析正文绝不写入插件日志。
• footer 状态小件:侧边栏底部常驻连接状态点(sidecar 连接态 + 速览),点击打开 Agent Center。
• /sidecar 斜杠命令:会话输入框内的只读状态速览(daemon 状态、连接健康度、working/waiting 计数、按项目分组的活跃会话);选择末尾的「Agent Center」动作可打开 Agent Center。
• 设置卡:dsh 设置页出现「Agent Sidecar」卡片(设置命名空间 agent-sidecar)。analysis.provider / analysis.model 以成对路由呈现:双空表示宿主默认,双非空表示显式路由,partial pair 不能保存;非 live 的 daemon/sidecar/stream 组只显示 profile patch + 重启说明。
• daemon 托管:探测-领养-否则托管(probe-adopt-else-host)策略管理 sidecar daemon 生命周期,详见[下文](#daemon-托管策略)。
• 实时数据面:host 半区经 Unix socket 消费 daemon(status 快照对账 + subscribe 事件触发),浏览器经同源 SSE 实时刷新。
• skill 内嵌提供:skill.provide(默认开)经 dsh skill 注册表提供 agent-sidecar skill,装插件即得、无需运行安装脚本;文件系统已安装的同名 skill 自动优先(dsh 注册表按名合并,文件系统层胜出,无需探测)。
• better-sidebar 可选摘要 Tab(软依赖):装有 dsh-better-sidebar 时注册紧凑「Sidecar」侧边 Tab(连接点 + 计数 + 最近会话摘要);未装静默跳过;Tab 不可见时释放订阅,不额外轮询、不另建 SSE。
• 跟随宿主 locale 的中英双语界面:向 dsh locale 服务注册中英文词典,采用宿主当前语言并跟随 locale/change;仅在宿主 locale 服务缺席时回退到插件内置中文,不会在正常 dsh Web 中形成默认中文孤岛。

前置条件

• dsh ≥ 0.1.1-rc.2(package.json 的 engines.dsh / dsh.engines.dsh 均为 >=0.1.1-rc.2)。
• peer 依赖 @deepseek-ai/cordis@^4.0.1 与 @deepseek-ai/dsh-agent@^0.1.1-rc.2 均为 optional,由 dsh profile 树提供,无需手工安装。
• agent-sidecar CLI(可选):daemon 托管(自动拉起)与 macOS LaunchAgent 检测需要本机可调用的 agent-sidecar(或经 sidecar.command 配置的任意调用形态,如 ["python3", "/path/to/agent-sidecar.pyz"])。插件绝不代装 sidecar;安装方法见[主仓 README](../README.md#installation)。
• 不装 CLI 也能用:只要已有 daemon 在跑(仓库 checkout 手动拉起、LaunchAgent 等),插件经 Unix socket 探测后只读领养它,不掌握其生死。
• Node/pnpm 仅开发本插件时需要;npm 包携带预构建产物,安装免构建。

安装

dsh plugin add 委托 pnpm 解析,故支持 pnpm 的三种包来源(将 web 换成你的 profile 名即可):

# ① npm 包名
dsh plugin --profile web add @shendeguize/dsh-agent-sidecar

# ② git 来源(monorepo 子目录,须带 path 选择器)
dsh plugin --profile web add github:shendeguize/AgentSideCar#path:plugin

# ③ 本地路径(仓库 checkout)
dsh plugin --profile web add /path/to/agent_sidecar/plugin

注意事项:

• registry 镜像:若本机默认 npm registry 是镜像(如 npmmirror),@deepseek-ai / @shendeguize scope 可能滞后或 dist-tag 陈旧,建议把这两个 scope 指向官方 registry(本目录内 .npmrc 即此写法)。
• profile 用法:对不存在的 profile,dsh plugin --profile <name> add … 会先初始化它;自定义 profile 需在其 manifest 的 bundles 中包含 @deepseek-ai/dsh-web-app 才有 Web 界面(dsh web 等价于 dsh --profile web)。启动:dsh --profile <name> [--port N]。
• 卸载:dsh plugin --profile <name> remove @shendeguize/dsh-agent-sidecar,幂等、可重装。

装好后的主要入口与表面:

1. dsh 主侧栏 → 一等「Agent Center」入口,打开官方 Modal 承载的 Agent Center overlay;

2. 侧边栏 footer → 可点击的状态小件,打开同一 overlay;

3. 会话输入框 /sidecar → 只读摘要及打开同一 overlay 的「Agent Center」动作;

4. 会话页顶部 Tab 环 → 保留的「Sidecar」第二入口;

5. 设置页插件区 →「Agent Sidecar」设置卡。

安装 dsh-better-sidebar 后还会出现可选「Sidecar」摘要 Tab;它是软依赖,不影响以上原生入口。

命令行验证:curl http://127.0.0.1:<port>/plugins/agent-sidecar/api/state 应返回含 daemon / board / capabilities 的 JSON 快照;GET …/api/stream 为 SSE 流;GET …/api/session/<id> 为单会话详情(含融合时间线首页),GET …/api/session/<id>/timeline?cursor=&limit= 分页回溯历史;GET …/api/lineage/<id>、GET …/api/search?q=、GET …/api/projects 为 M3 读面;POST …/api/action 为幂等动作信封(inject.prepare / inject.execute / analysis.* / daemon.retry)。

时间线公共合同

• 规范条目与排序:host 融合 DSH live 事件、按次晚绑定的 sessionQuery、sidecar replay 与有界事件缓冲。带 seq 的条目按 seq + kind + text 去重,因此同一原生 seq 的多个内容块不会被误删;无 seq 条目按 ts + kind + text 去重。seq 域严格按 seq 排序,同 seq 内 DSH 条目在前、兄弟块保留稳定顺序,再与无 seq 条目按时间交错。
• 分页收敛:同 seq 兄弟组不会跨分页边界拆分。重叠页按同一身份去重;后续页面若为既有 DSH 条目补到规范文本,client 会升级空文本条目而不是复制一条。nextCursor 只随历史分页前移;listen 的最新窗口不会重置历史游标。
• 来源与降级:每页除兼容性的 sources 外,还返回不含内容的 sourceOutcomes(liveSession / sessionQuery / sidecarReplay / buffer,取值为 succeeded / unavailable / not_found / replay_unsupported / source_failed)以及 degraded、reason。部分来源失败时保留现有/可用事件并显示降级提示;全部可用来源失败且没有新条目时明确提示「未能加载新事件」并给出刷新入口。未知或不一致的新字段关闭失败为「来源状态无法确认」,不会把上游错误文本、路径或会话内容带到 UI。
• 晚绑定与请求代际:sessionQuery 每次使用时重新解析,后挂载的服务无需重载 client 即可生效。详情元数据与时间线各自有代际;新的最新窗口刷新会取消并取代旧分页/listen/刷新任务,晚到响应不能回滚条目、来源健康、header 或游标。已显示的 partial 警告只会被新代际中经过验证的健康页清除。

注入资格矩阵

资格判定由 host 在仍持有完整只读会话行时派生,浏览器只接收 {allowed, reason};原始 extra、远端标记、parent ID 与私有路径不跨该边界。

• inject.enabled=false:全局门关闭,所有写动作服务端 403;这是独立于下列单会话资格的总开关。

…(truncated)