运维指南

本页是日常参考：控件在哪、每个字段做什么、实例跨重启怎么表现、存储与安全怎么配。内容对应 0.4.0 / DeepSeek Harness 0.2.1-rc.2。

1. 控制面

驱动插件有三种等价方式：

控制面	用途
设置 → A2A 连接	主 UI：创建/编辑/启停/删除，查看对端、会话、任务
`/a2a` 命令	DSH 聊天会话里的文字备用路线
仅回环 `/a2a/api`	脚本、测试、集成；见 HTTP API

三者调用同一个 facade，所以状态不会互相矛盾。面板每 3 秒自动刷新。

2. 面板

2.1 入站 Servers

每张卡片显示名称、端点路径、preset 徽章、鉴权状态、派生技能 chips，以及实时 AgentCard URL。操作：

操作	效果
启用 / 停用	注册或注销卡片与端点路由；记录与会话池保留
编辑	改名称/描述/版本/preset/token；重建卡片/技能并换装活实例
删除	dispose 活实例并删除持久化记录
清除鉴权	删除已存 Bearer Token，以匿名实例重建

创建/编辑表单有名称、版本、preset、Bearer Token、描述。技能创建后显示，不需要手填。 preset 选择器只列真实 roster 预设，并预选部署默认。

2.2 出站 Servers

添加是两阶段流程：

填远端 AgentCard URL（和可选 token），点导入。
核对读到的名称/版本/描述/端点/技能，调整本地名称、preset、超时，点连接。

已连接卡片显示状态点、导入技能数、工具数，失败时显示 lastError。操作： 启用/停用、刷新（重读卡片并重注册工具）、编辑（名称/preset/超时/token）、删除。

Token 通过凭据服务单独存储；编辑时 token 留空会保留原值。入站表单有清除鉴权；出站没有清除按钮：通过 outbound.setAuth 提交空 token；编辑表单里 token 留空会保留原值。

2.3 连接与任务

三张表：

入站对端——谁在调用这个 DSH：来源身份、任务数/活跃数、流式指示、首次/最近时间、关闭。
入站会话——每个 contextId 一行：实例、preset、运行中/空闲、任务/活跃数、流式、首次/最近时间、 取消活跃、关闭。
任务——最近 20 条任务：id、技能、来源实例、状态、取消。

语义：

取消活跃中止该上下文所有非终态任务；会话保持打开。
关闭额外释放该上下文的活跃会话句柄。它是资源释放，不是会话墓碑：同一 contextId 的下一个任务会重新打开新句柄。
对端上的关闭会移除该对端的 registry 记录，不删除它的任务。

3. `/a2a` 命令参考

命令在 DSH 聊天会话里使用。列表与状态类输出 JSON。

命令	用途
`/a2a status`	整插件快照
`/a2a presets`	Agent preset 名单
`/a2a inbound list`	入站实例
`/a2a inbound create <name> [preset] [description]`	创建入站实例
`/a2a inbound remove <id>`	删除
`/a2a inbound enable\|disable <id>`	启停路由
`/a2a outbound list`	出站实例
`/a2a outbound create <agentCardUrl> [name] [preset]`	创建出站连接
`/a2a outbound remove <id>`	删除
`/a2a outbound enable\|disable <id>`	启停
`/a2a outbound refresh <id>`	重读远端卡片
`/a2a tasks`	任务列表
`/a2a task get <taskId>`	单条任务
`/a2a task cancel <taskId>`	取消任务
`/a2a sessions`	按上下文的会话视图
`/a2a session cancel <contextId>`	取消该上下文的活跃任务
`/a2a session close <contextId>`	释放该上下文的活会话
`/a2a peers`	入站对端注册表
`/a2a help`	用法

参数以空白分隔。入站描述是可选 preset 之后的剩余单词；需要更丰富的字段时用面板或 HTTP API。

4. 生命周期语义

创建——持久化记录、派生技能、解析鉴权、组装运行时；启用时注册路由。
更新——持久化 patch，重新派生技能（preset 可能变了）、重新解析鉴权，在保留启用状态的前提下替换活实例。
启用/停用——只注册/注销路由。记录、技能、会话池保留；停用实例在启动时仍会组装，但不路由。
删除——dispose 活实例并写入空 tombstone 行；重启后不会复活。
出站连接——读卡片、按技能注册工具、持久化记录。连接失败返回错误并保留失败视图便于排查；记录在连接尝试前已保存。
出站刷新——从卡片重建 registry 并重注册工具。编辑用新的名称/preset/超时重建连接，并重新应用已存 token。
重启——重新组装持久化的入站/出站实例；启用的会恢复。活跃会话与流订阅不恢复。

5. 配置

插件配置刻意最小。实例不在 cordis.patch.yml 里配置；它们存在于 a2a 域，由面板管理。

- id: a2a
  config:
    baseUrl: http://127.0.0.1:3080   # 可选；省略时从 webServer 派生
    subagentProvider: in-process     # 默认
    defaultTimeoutMs: 60000          # 默认出站超时
    inboundTimeoutMs: 600000         # 每个入站任务的执行预算；0 关闭
    requestsPerMinute: 120           # 每个入站来源的限流；0 关闭
    maxConcurrentTasks: 32           # 每个入站实例的并发上限；0 关闭
    maxBodyBytes: 1048576            # 入站 HTTP 请求体上限
    outboundRefreshMs: 300000        # AgentCard 自动刷新间隔；0 关闭

字段	默认	含义
`baseUrl`	web server 端口，其次 `DSH_A2A_PORT`，最后 `3000`	所有入站 AgentCard 的对外 base URL
`subagentProvider`	`in-process`	subagent 执行器接缝的 provider 名
`defaultTimeoutMs`	`60000`	出站连接每次调用的默认超时
`inboundTimeoutMs`	`600000`	每个入站任务的执行预算；超时落 `FAILED`
`requestsPerMinute`	`120`	每个入站来源的滑动窗口限流；超限返回 HTTP 429
`maxConcurrentTasks`	`32`	每个入站实例的并发任务上限
`maxBodyBytes`	`1048576`	入站 A2A 请求体上限
`outboundRefreshMs`	`300000`	启用中的出站连接自动刷新 AgentCard 的间隔

入站会话工作目录是 $DSH_HOME/a2a-sessions（启动时创建）。DSH_HOME 默认 ~/.dsh。

6. 宿主服务

只有 storageDomain 是必需的。其余服务都是探测式可选；缺少某个只会让对应能力空闲，不会让整个插件挂掉。

服务	使用方	缺失时的效果
`storageDomain`	两端	必需；插件不挂载
`webServer`	入站路由、面板 API	入站端点/卡片与面板 API 空闲
`agents`	入站 session 执行器	入站任务走 `refuse` 执行器
`attachments`	入站图片/文件 part	原始附件降级为占位文本
`agentPresets`	preset 选择、技能派生	preset 默认与派生技能退化为 `chat`
`skills`	技能派生	卡片回退到 `chat`
`credentials`	token 存储/解析	GUI 写 token 失败；外部 export 的环境变量仍可用
`subagents`	subagent 执行器	subagent 执行器不接线
`tools`	出站工具注册	出站连接无法注册工具
`commands`	`/a2a`	聊天命令不注册

基础 web profile 已挂载全部。自定义组合若想要完整能力，应包含 storageDomain、webServer、agents、agentPresets、skills、tools、commands。

7. 存储

a2a 域默认走 profile 的 JSON 后端。表与内容见核心概念。

只把 a2a 域路由到 SQLite：

- id: storage-domain
  config:
    backend: json
    routes:
      a2a: sqlite
- insert:
    - id: storage-sqlite
      name: '@deepseek-ai/dsh-storage-sqlite'
      config:
        path: /absolute/path/to/a2a.sqlite

运维注意：

一个 DSH_HOME 只允许一个写者。 两个 DSH 进程共享 home 会写同一个 JSON 域；不要让两个实例指向同一个存储根。
任务与实例持久化。 活跃会话、流订阅、对端注册表都在内存里，重启即清空。
域里存的是 JSON 字符串，格式变化由域的 version 字段守护。升级前备份 JSON/SQLite 文件。
会话日志由 DSH 正常的 session persistence 写到 $DSH_HOME/sessions/...；插件的工作目录是 $DSH_HOME/a2a-sessions。

8. 对外暴露与安全

面板 API 在设计上仅回环。把 web app 放到反向代理后面，也不会让 /a2a/api 可远程调用。
A2A 端点与 GUI 共用同一个 web server。如果把该 server 暴露到网络，给每个入站实例配置 Bearer Token，并在代理层终止 TLS。插件本身不提供 TLS；它自带进程内请求/请求体/并发限制，但没有分布式配额。
Token 通过凭据服务存储，按名称引用；绝不写入 a2a 域或 AgentCard。
每个入站实例用不同 token，避免一次泄露就拿到所有已发布 agent 的访问权。
出站 token 每次调用时解析，轮换凭据后下一次工具调用即生效，无需重启。

9. 升级与卸载

升级：

dsh plugin --profile web add @hanphone/dsh-a2a@latest

安装后重启 dsh web。实例与任务在域里，升级后保留；活跃会话不保留。

卸载：

dsh plugin --profile web remove @hanphone/dsh-a2a

卸载不会删除 a2a 域数据。只有确认要丢弃实例定义与任务历史时，才删除域行（或存储文件）。

10. 兼容性

插件为支持的 DSH 版本声明 peer 范围。DSH 0.1.7+ 会跑 peer 预检，范围不覆盖运行时版本就拒绝加载。预检报错时，把插件与 harness 一起升级；不要在没有跑兼容性流程的情况下擅自放宽范围。

精确范围、验证流程与发布记录见 Harness 兼容性。

1. 控制面​

2. 面板​

2.1 入站 Servers​

2.2 出站 Servers​

2.3 连接与任务​

3. /a2a 命令参考​

4. 生命周期语义​

5. 配置​

6. 宿主服务​

7. 存储​

8. 对外暴露与安全​

9. 升级与卸载​

10. 兼容性​