前言¶
在 DeepSeek Harness（dsh）里接命理、黄历、占卜类能力时，常见做法是自建计算逻辑或自行对接各家 HTTP 接口，维护成本高，且结果格式与线上产品不一致。Ancient Echoes 已提供统一的 Tools API 与 MCP；若你只想在 dsh 会话里以「工具」形式只读调用同一套接口、不在本地重算排盘，需要一个薄封装插件。
下面介绍社区插件 dsh-ancient-echoes（维护者 FlamesCN，分类：联网工具）：每次工具调用转发到托管的 Ancient Echoes Tools API（POST /api/v1/tools/<tool>），返回与 AE Web 应用、REST API、AE MCP 一致的结构化结果，不在本机实现计算、不缓存命盘数据。
这是什么¶
- 定位：面向 dsh 的只读透传插件，对接 Ancient Echoes Developers 文档中的 Tools API。
- 仓库：FlamesCN/dsh-ancient-echoes，许可证 MIT；当前 package 版本 0.1.0，要求 Node >=20，dsh >=0.2.1-rc.2 <0.3.0（README 注明 dsh 尚未 1.0，需按具体 dsh 版本验证）。
- 可选替代：同源能力的 MCP 端点为
https://www.ancientechoes.ai/api/v1/mcp（Streamable HTTP）；Skill/agent 相关仓库见 FlamesCN/ancient-echoes-mcp。
核心功能¶
透传与工具注册¶
插件根据配置向 dsh 注册一组工具名；调用时请求 baseUrl（默认 https://www.ancientechoes.ai）下的 API，超时默认 45000ms，模型可见结果长度默认上限 60000 字符（完整 canonical 值仍保留）。
配置项 tools 含义如下：
| 取值 | 行为 |
|---|---|
core（默认） |
注册 10 个常用工具（见下表） |
all |
注册 AE 注册表中的全部 38 个工具（八字、紫微、奇门、七政、吠陀、西洋占星、13 种占卜、择日、黄历、RAG 等） |
| 显式数组 | 按名称子集注册 |
tools: core 时 dsh 工具与 AE 工具对应关系：
| dsh 工具 | AE 工具 |
|---|---|
bazi_calculate_chart |
bazi.calculate_chart |
bazi_compare_charts |
bazi.compare_charts |
bazi_analyze_wealth |
bazi.analyze_wealth |
ziwei_calculate_chart |
ziwei.calculate_chart |
lingxi_rag_search |
lingxi.rag_search |
lingxi_rag_query |
lingxi.rag_query |
almanac_get_day |
almanac.get_day |
election_find_good_days |
election.find_good_days |
divination_preview_liuyao |
divination.preview_liuyao |
divination_preview_meihua |
divination.preview_meihua |
tools: all 时工具名与参数 schema 由 AE OpenAPI 快照生成（README 称快照为 AE Tools API 1.3.0）。
另注册一个辅助工具 <toolPrefix>ancient_echoes_guide（toolPrefix 默认为空则为 ancient_echoes_guide），返回内置 condensed 使用说明（字段约定、错误码、隐私边界），不发起网络请求、无需 API Key。
返回结构与错误¶
成功响应包含 api_version、request_id、calculation { capability, version } 与 data；向模型转述结果时应注明 calculation 版本，避免混用不同版本。
常见错误码（含可操作建议）：
| Code | 含义 |
|---|---|
tool_entitlement_required |
账户套餐不含该工具 |
tool_quota_exceeded |
配额：200 次/日、30 次/分钟，需遵守 Retry-After |
tool_scope_required |
Key 缺少 tools:read / tools:invoke |
unauthorized |
Key 缺失或无效 |
invalid_argument、tool_invocation_failed |
参数问题，非服务宕机 |
鉴权与安全边界¶
- 除
ancient_echoes_guide外，每次远程工具调用前解析凭证；缺失则拒绝，不进行网络 I/O。 - 默认凭证引用名
apiKeyRef：ANCIENT_ECHOES_TOKEN（优先 dsh 凭证存储，其次环境变量）；凭证不会写入工具输出或日志。 - 只读：仅注册工具，不写文件、不执行 shell；除
baseUrl外无其它外连。出生信息等仅作为单次调用参数传递，不缓存。 - 发布包仅含编译后的
lib/等白名单文件；README 强调结果为参考性结构化证据，不构成 deterministic 预测或医疗/法律/投资建议。
安装与启用¶
官方推荐通过 dsh 插件命令安装（使用 web profile）：
dsh plugin --profile web add dsh-ancient-echoes
dsh --profile web --dump-config | grep -A2 dsh-ancient-echoes
若本地已有插件目录 checkout，可改为路径安装：
dsh plugin --profile web add ./path/to/dsh-ancient-echoes
在 Ancient Echoes 灵犀设备页 获取 Web API Key（sk-…），再配置凭证。任选其一：
- 环境变量（调试可用）：
export ANCIENT_ECHOES_TOKEN=sk-...
- 推荐：dsh Web UI → Settings → Models/credentials 保存
ANCIENT_ECHOES_TOKEN；或在插件/控制台会话中await ctx.credentials.set(credentialRef('ANCIENT_ECHOES_TOKEN'), 'sk-…')。存储位于$DSH_HOME/.credentials.yaml，优先级高于环境变量，轮换后下次调用生效，无需重启 harness。
配置里仍有明文 apiKey 可覆盖，但 dsh --dump-config 会打印明文，仅建议本地调试。
主要配置字段（摘自 README）：
| Key | 默认 | 含义 |
|---|---|---|
apiKeyRef |
ANCIENT_ECHOES_TOKEN |
凭证引用 |
apiKey |
'' |
明文覆盖（调试用） |
baseUrl |
https://www.ancientechoes.ai |
API 根地址 |
tools |
core |
core / all / 工具名数组 |
toolPrefix |
'' |
工具名前缀，如 ae_ |
timeoutMs |
45000 |
单次调用超时 |
maxResultChars |
60000 |
面向模型的结果截断上限 |
开发自检可用 dev profile：
dsh --profile dev --dump-config | grep -A2 dsh-ancient-echoes
ANCIENT_ECHOES_TOKEN=sk-... dsh --profile dev
典型用法¶
在 harness 中为智能体启用插件后，模型即可调用已注册工具（例如 bazi_calculate_chart），参数 schema 与 AE OpenAPI 一致；首次可先调用 ancient_echoes_guide 了解字段与错误约定，再按需调用 core 或 all 中的具体工具。
本地开发插件本身（非最终用户必经步骤）时，仓库提供：
npm install
npm run build
npm test
npm run check:pack
适用场景与注意¶
适合：已在 Ancient Echoes 开通 API、希望在 dsh 智能体中与 AE 产品同源结果对齐的开发者；需要八字/紫微/黄历/择日/占卜预览或 tools: all 全量注册的场景。
注意：
- 插件以当前 dsh 进程权限运行；安装前请阅读仓库源码与 MIT 许可证，确认外连域名与凭证策略符合你的环境。
- 远程工具依赖账户套餐与 Key 权限；遇
tool_entitlement_required不应擅自换成其它工具顶替。 - dsh 生态为「一切皆插件」；插件目录站 skillhub.cn 上的条目 为社区收录，与 DeepSeek / 幻方无官方从属关系。
结尾¶
dsh-ancient-echoes 把 Ancient Echoes Tools API 以只读透传方式接入 dsh，避免本地重复实现排盘逻辑，并与 AE 其它入口共享同一套结构化输出。查阅目录与源码：
- 目录页：https://www.skillhub.cn/plugins/FlamesCN/dsh-ancient-echoes
- GitHub：https://github.com/FlamesCN/dsh-ancient-echoes
- API 文档：https://www.ancientechoes.ai/developers
