Asa 研究桥接 benjiyaya/dsh_AsaAgent

dsh-asa-agent — DeepSeek Harness 里的 Asa

Asa 的研究流水线、完整的 Asa 智能体回合、Asa 的健康统计，全部跑在 DSH 会话里 —— 三个 MCP 工具加一个 doctor，桥接自同一个本地端点。

dsh-asa-agent 是 DeepSeek Harness 插件包。它挂载宿主的 @deepseek-ai/dsh-mcp-client（传输方式：streamable-http），连上 Asa 网关已经在 POST /mcp 提供的 MCP 服务器，再加一个原生工具，用来告诉你这座桥是否健康。

状态 —— v0.1.0，尚未安装。 本文档基于 Asa 0.1.0 和 2026-10-24 的 DSH 桌面配置档编写。插件还没装进任何实际运行的配置档，所以下面的快速上手是安装步骤，不是一次已完成运行的报告。每一步需要你确认的地方都会明确写出。

你会得到什么

| 工具 | 类型 | 作用 |
| mcp__asa__asa_research | 桥接的 MCP 工具 | 对某个主题运行 Asa 的递归研究流水线：规划 → 网页搜索 → 抓取 → 写入 Vectorless RAG 知识库 → 带置信度分析 → 综合出带引用的报告。返回报告路径和运行统计。可能耗时数分钟。 |
| mcp__asa__asa_message | 桥接的 MCP 工具 | 给 Asa 发消息并返回回复。传 session_id 可继续对话。最多接受 10 个附件。 |
| mcp__asa__asa_status | 桥接的 MCP 工具 | Asa 的健康与记忆统计，包括 Docker 是否可达。 |
| asa_doctor | DSH 原生工具 | 探测配置好的网关，报告可达性、发现的工具，以及失败时的修复提示。 |

说白了： DSH 多了三个工具，它们就是 Asa；还多了一个工具，告诉你另外三个为什么不回话。

前三个名字来自 DSH 的 MCP 命名规则 mcp__<serverName>__<rawName>。Asa 的服务器叫 asa，它的工具本来就叫 asa_research、asa_message、asa_status —— 所以名字里 asa 出现了两次。这是对的，不是笔误。改插件配置里的 serverName，前缀就跟着变。

说白了： 工具名是「MCP 命名空间」+「工具自己的名字」，而两者恰好都叫 asa。

为什么是三个工具，而不是十五个

这次集成早先的规划文档提出要新建一个 stdio MCP 服务器，大约十五个工具（asa.recall、asa.record、asa.audit、asa.sleep、asa.forget、asa.kb.、asa.skills.、company.、asa.ask、asa.message.send）。那个服务器并不存在。 今天 Asa 的 MCP 端点上没有这些工具中的任何一个。

存在的是 Asa 的网关 MCP 服务器 —— Streamable HTTP、无状态 JSON 模式、正好三个工具 —— 本插件桥接它，中间不再加第二个服务器。虚构出来的那套接口记在下面的路线图里，标注为未实现。

说白了： 文档只讲能用的三个工具，把不存在的十五个归到「还没做」下面，而不是假装它们存在。

快速开始（约 5 分钟）

路径约定： <asa-repo> 是你本地 Asa 检出目录的路径，<plugin-dir> 是这个仓库在你机器上检出后的路径。两者都是占位符，不是真实目录——请替换成你自己的绝对路径。

你需要：本地 Asa 检出、一个 DSH 桌面配置档，以及一个空闲终端。Asa 自己的 README 把 Node 22+ 和 Python 3.12+ 列为前置条件。

1. 启动 Asa 网关

在一个可以一直开着的终端里：

cd <asa-repo>
npm run setup
npm run dev:gateway

npm run setup 只在首次运行时需要，且可重复执行——之后再跑可以跳过。npm run dev:gateway 会阻塞，在 http://localhost:8787 上提供网关服务；让它一直跑着，下一条命令换第二个终端执行。

大白话： 这里 Asa 是服务端。它不跑起来，什么都干不了。

2. 确认它已启动

在第二个终端里：

Invoke-RestMethod http://127.0.0.1:8787/api/health

你应该看到 ok : True、name : asa 和 version : 0.1.0。/api/health 是回环地址上的免认证路由——在还没牵扯 DSH 之前，用它做一次快速检查很管用。

大白话： 这是在问 Asa「你还活着吗？」，既不需要 token，也不需要 MCP 客户端。

3. 安装插件包——这一步需要你批准

插件安装走 harness，而不是在配置档里执行 shell 的 npm install。在 DSH 中，用 plugin_manager 工具的 install_bundle 动作安装插件包，把插件目录作为 target 传入：

{
"action": "install_bundle",
"target": "<plugin-dir>"
}

这段不是 shell 命令——它是 plugin_manager 工具调用的参数对象，列出来是为了让你看清确切的 target 路径。

macOS 和 Windows 会弹出插件安装批准提示，你必须接受。如果结果里出现 pendingBuilds 条目，说明那个安装脚本还需要单独明确批准才能运行。这两步都不能无人值守。

大白话： DSH 会问你「我可以装这个吗？」，你得回答可以。不会有任何东西悄悄装上。

4. 验证桥接

在 DSH 会话里调用 mcp__asa__asa_status——不带参数——然后运行 asa_doctor，它同样不带参数。两者的参数对象一样：

{}

第一次调用证明桥接能通流量；第二次调用证明它指向了正确的位置，并在不对时告诉你该修什么。

大白话： 一次调用向 Asa 要统计信息，另一次问插件接线是否正常。

成功的样子

asa_status 返回的 JSON 文本大致如下：

{
"docker": true,
"kb": { "documents": 42 },
"mind": { "...": "memory statistics" }
}

这些键来自 Asa：docker 是它 Docker 探测得到的布尔值，kb / mind 是它的知识库与认知记忆统计。asa_doctor 则报告可达性、它发现的工具，以及修复提示。
通俗地说： 健康的回答会显示 Docker 的状态，外加 Asa 的记忆计数器；出问题的回答会告诉你下一步该怎么做。

配置一览

八个配置项全部可选。默认值如下：

| 配置项 | 默认值 | 什么情况下需要改 |
| url | 取 ASA_MCP_URL 环境变量，否则用 ASA_GATEWAY_PORT（默认 8787）走回环地址 | Asa 跑在别的端口或别的机器上。 |
| serverName | asa | 你已经桥接了另一个名为 asa 的服务器。 |
| token | （未设置）* | Asa 在远端，必须提供配对 token。 |
| mcp | true | 保留 asa_doctor，但跳过 MCP 桥接。 |
| primer | true | 你不想要关于 Asa 的系统提示词段落。 |
| toolCallTimeoutMs | 600000 | 你的机器上研究任务要跑超过 10 分钟。 |
| failOnStartupError | false | 你希望 Asa 挂掉时 harness 启动直接报错。 |
| doctorTimeoutMs | 15000 | 机器较慢时探测会超时。 |

在配置档的补丁层里，id: dsh-asa-agent 下可以覆盖以上任意一项。注意补丁行的 config 是整体替换，不做深度合并，所以想保留的配置项都要重新写一遍。

通俗地说： 你可以把它指向另一台 Asa、给它一个 token，或者关掉某个功能——每个默认值都经过挑选，什么都不改也能在本地原版 Asa 上正常工作。

安全说明，一段话讲完

如果网关在回环地址上，Asa 自己的鉴权会放行不带 token 的调用——这是 Asa 的设计，不是插件的缺陷，也是默认 URL 用 127.0.0.1 的原因。把插件指向远端 Asa，就必须提供配对 token。asa_message 调用的不是只读 API：它跑的是完整的 Asa 智能体回合，所以影响范围就是 Asa 自己的工具面（工作区读写、沙箱执行、网页抓取）。在把任何东西暴露到 localhost 之外以前，请先了解：插件自身不提供任何传输层安全——走明文 http:// 时，你的配对 token 和每个工具载荷都能在网络上被读到。

通俗地说： 在同一台机器上，Asa 不用密码就信任你。消息工具是一整个智能体，不是一次查询。

故障排查速查

- 会话里没有 mcp__asa__* 工具——bundle 没安装或没启用，或者桥接在启动时失败了。运行 asa_doctor；如果这个工具也没有，说明插件本身没加载。
- asa_doctor 报 unreachable——Asa 的网关没在运行，或者 url 指向了别处。用 npm run dev:gateway 启动它。
- 401 "pairing required"——url 指向了非回环主机（比如局域网 IP），又没带 token。改用 127.0.0.1，或者设置 token。
- 调用看起来卡了好几分钟 — asa_research 本来就要跑几分钟；toolCallTimeoutMs 默认是十分钟。如果调用停在接近十分钟的位置，回来时什么都没做，说明 Asa 停在自己的 ask_user 确认提示上，而 Asa 窗口里没人应答：这一轮会以「未确认」的状态继续。去 Asa 界面里回答这个提示，或者把 Asa 的 ASA_ASK_TIMEOUT_MS 调低，让没人能答的提示尽快失败。

说白了： 几乎所有失败要么是「Asa 没在运行」，要么是「URL 写错了」——先查这两条。

文档

这份 README 就是完整的公开指南：安装、配置、安全，以及大家实际会踩的坑。更长的参考材料——架构走读、详尽的工具参考、部署与授权风险说明——由内部维护，不在本仓库里。

路线图 — 尚未实现

这张表里的东西，今天没有一个作为 Asa MCP 工具存在。它只是早先规划文档提出的设想；当成愿望清单看，别当成 API。

| 提议 | 层 | 状态 |
| asa.recall、asa.record、asa.audit、asa.sleep、asa.forget | 认知记忆循环 | 尚未实现 |
| asa.kb.query、asa.kb.ingest、asa.kb.list | 知识库 | 尚未实现 |
| asa.skills.list、asa.skills.read | 技能 | 尚未实现 |
| company.recall、company.remember | 公司大脑 | 尚未实现 |
| asa.ask、asa.message.send | 有界问答循环、发完即忘的收件箱 | 尚未实现 |
| asa.spawn、asa.run | 完整自主循环 | 尚未实现 |
| stdio 传输（每个会话派生一个） | 传输 | 尚未实现 — v0.1.0 只有 Streamable HTTP |

补充背景：在这个插件出现之前，Asa 的 MCP 接口是缩小过的。它自己仓库里的检查（npm run check:mcp）断言 asa_recall、asa_ingest 和 asa_sandbox_run 不在工具列表里。路线图里再把这些加回来，属于设计提议，不是恢复旧功能。

说白了： 大家期待的记忆和知识库工具并不存在——Asa 有意删掉了一部分，剩下的从来没做过。

许可证

插件代码：MIT — 见 LICENSE，© Memkist。Asa 本身是另一个本地产品；这里不再分发它，它也不在 MIT 授权范围内。

说白了： 你可以随意复用这个插件的代码；但这跟你要连接的 Asa 应用没有关系。

测试环境： 插件 0.1.0 · Asa 0.1.0 · DSH 桌面配置档 · 2026-10-24。这一行记录的是写这份文档时对应的版本；插件还没安装，所以这不代表上面每一步都端到端跑过。