前言¶
在 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
