Skip to content
dsh marketplace

dsh-aoci

Verified

dsh-aoci · v0.2.0 · MIT · Web UI

AOCI-CODE cognition layer for DeepSeek Harness: one-shot /aoci command + dynamic MCP bridge for governed, Git-versioned repository/database cognition.

Install

dsh plugin add dsh-aoci

Confirm the layer applied with dsh --profile default --dump-config — see the install guide.

Source

Tags

Creators

Readme

dsh-aoci

面向 DeepSeek Harness 的 AOCI-CODE 认知层：一条斜杠命令即可让 AI 获得受治理、Git 版本化的仓库与数据库认知。

English | 简体中文

摘要

dsh-aoci 将 AOCI-CODE（实现 AOCI——AI 面向认知基础设施——范式的本地优先 stdio MCP 服务器与 Go CLI）接入 DeepSeek Harness（DSH）插件生态。它将确定性治理（初始化、基线建立、验证）与语义创作（由模型在 AOCI 治理协议约束下撰写 FRAS 条目）相分离，并通过三个互补的模型可见面暴露认知：

  • 九个 MCP 工具（mcp__aoci-<slug>__aoci_rules / aoci_overview / aoci_get_entries / aoci_search / aoci_maintain / aoci_update_entry / aoci_remove_entry / aoci_header / aoci_report），由动态 MCP 桥按需注册，免去"每仓库一条静态配置 + 重启"；
  • 十一个确定性工具（aoci_status、aoci_verify、aoci_check、aoci_scan、aoci_panel、aoci_use、aoci_unbind、aoci_relations、aoci_impact、aoci_lineage、aoci_db），承担治理、System Cognition 查询、数据库预检与智能体自主选路；
  • 一键斜杠命令 /aoci [路径]：带路径时解析（绝对路径，或相对 defaultRoot）；不带路径时自动定位当前会话工作区仓库；条件初始化/建基线 → 绑定 MCP 桥 → 经 agent.steer 向当前智能体提交建索引指令——一次调用完成认知接入。可选标志：--locale、--scope、--agent、--skip-scan、--db。

AOCI-CODE 采用 FSL-1.1-MIT（source-available）许可；本插件不捆绑其二进制——仅引导从官方发布渠道下载并做 SHA-256 校验。

适用范围与兼容性

  • 实测运行环境：DSH Desktop >= 2.7.0（API ^1.2.0）；harness 运行时 ^0.1.1-rc.1 || ^0.1.5-alpha.1（cordis ^4.0.2）；web profile。
  • Peer 依赖（宿主启动时提供）：@deepseek-ai/cordis、dsh-settings、dsh-system-prompt、dsh-tools、dsh-jobs、dsh-llm、react、react-dom。
  • 运行时依赖：schemastery、@modelcontextprotocol/sdk。
  • 前置二进制：官方 AOCI-CODE Release 下载并 SHA-256 校验的 aoci（默认 C:/aoci/bin/aoci.exe）。

模型可见面

面 名称 用途
认知读取 mcp__aoci-<slug>__aoci_rules、...__aoci_overview、...__aoci_get_entries、...__aoci_search 加载与检索受治理的认知地图
认知维护 ...__aoci_maintain、...__aoci_update_entry、...__aoci_remove_entry 协议约束下的增量更新
认知证据 ...__aoci_header、...__aoci_report 索引身份与 attestation
确定性治理 aoci_status、aoci_verify、aoci_check、aoci_scan、aoci_panel 健康、验证、基线、面板（status 同时报告 git head/工作区漂移）
System Cognition aoci_relations、aoci_impact <object>、aoci_lineage 依赖投影、影响分析、来源绑定链
数据库预检 aoci_db <source> 只读 database source access 预检（凭据仅环境变量引用）
智能体自主选路 aoci_use <路径>、aoci_unbind <slug> 按需绑定/解绑仓库
斜杠命令 /aoci <路径> 一键接入（绑定 + 指示 AI 建索引）

架构

DSH Web GUI (client) ── RPC/HTTP ──▶ DSH Host 半边（本插件）
                                        │ ctx.tools 动态注册
                                        ▼
                              aoci mcp（stdio，按需拉起）
                                        │ 九 MCP 工具
                                        ▼
                          仓库认知资产（aoci.txt 等，Git 版本化）
  1. 双面插件：包根为宿主（Node）半边；./client 导出为浏览器半边，经 DSH 的 __ModuleLoader__.load 协议注册。状态账本持久化于 profile 隔离的 state/aoci/（projects.json、runs.jsonl）。
  2. 动态 MCP 桥（AociBridge）：经 Node child_process 拉起 aoci --repo <root> mcp，以 @modelcontextprotocol/sdk 的 StdioClientTransport + Client 连接，发现九工具并注册到 ctx.tools；解绑时注销并终止进程。
  3. AOCI 治理语义（实测固化）：init 仅对未初始化仓库执行（探测 aoci.txt）；scan 仅在没有基线时执行（探测 .aoci/baseline.json）；既有基线以无参 aoci_maintain + 整批 aoci_update_entry 维护，由 verify/check 证明。
  4. 一键命令：/aoci [路径]（无参自动定位当前工作区）经 ctx.inject(['commands'], …) 注册，并以 agent.steer(createUserMessage(...))（plan-mode 提交模式）提交建索引指令。
  5. 压缩契约桥接：compactAociResults（将 Whole-Index 正文折叠为 receipt 的纯函数）与 compaction/end 恢复钩子（installAociCompactionGuard）将 AOCI 压缩纪律对齐到 DSH 会话压缩。

安装

前置

  • DeepSeek Harness profile（desktop >= 2.7.0 / runtime ^0.1.5-alpha.1 线）。
  • 从官方 AOCI-CODE Release下载 aoci 二进制（如 aoci_0.1.0-rc18_windows_amd64.zip），对照发布的 SHA256SUMS 做 SHA-256 校验，放到稳定绝对路径（默认 C:/aoci/bin/aoci.exe）。

步骤

cd <插件工程目录>
pnpm install
pnpm check            # typecheck + 单测 + 构建
pnpm pack             # dsh-aoci-<version>.tgz

dsh plugin --profile <name> add ./dsh-aoci-<version>.tgz
# 重启 DSH Desktop 后，在输入框执行：
#   /aoci D:\path\to\repo        （绝对路径）
#   /aoci ./relative                （需先配置 defaultRoot）

/aoci 之后，智能体将构建索引（rules → 完整 Overview → 分批 Maintain → verify/check → aligned）。后续会话复用同一份 Git 版本化认知；任务收尾自动维护。

配置参考

键 默认值 说明
binaryPath C:/aoci/bin/aoci.exe 已验证 aoci 二进制的稳定绝对路径。
defaultRoot ``（空） /aoci 与 aoci_use 相对路径的解析基准目录。
mcp.serverNamePrefix aoci 动态注册 MCP 工具的命名空间前缀。
mcp.toolCallTimeoutMs 120000 桥接 MCP 工具的单次调用超时。
projects[].root / slug / locale — 静态项目（可选；动态绑定无需预配置）。
projects[].dbSources[] [] 数据库数据源（sourceId、engine、databaseName、namespace、credentialEnv）。
projects[].schedule.cron 0 3 * * * 夜间健康检查（默认仅 verify）。

验证方法

插件经四种互补方式验证：

  1. 单元测试（15 例）：slug/凭据引用派生、五段 cron 匹配、MCP 条目组装、压缩折叠、schema 默认值、相对路径解析。
  2. 端到端链路（真实 aoci 0.1.0-rc18 二进制 + 真实 Git 仓库 + MCP SDK）：init 成功；scan 建立基线（6 文件 / 586ms）；verify 输出 JSON；九个 MCP 工具全部发现；aoci_header 经 MCP 返回索引身份。
  3. 集成自测（真实 Cordis 上下文 + 命令注入）：/aoci handler 注册、绑定 9/9 工具、agent.steer 提交成功。
  4. 加载器合成：dsh --profile web --dump-config 无错误解析插件条目与配置。

已知局限

  • 应用完全退出后不承诺后台调度继续执行。
  • 首次建索引耗时随规模增长（约 1 小时 / 20 万行）且消耗 API 额度。
  • 动态桥进程生命周期管理（崩溃重连）仍可强化。
  • 数据库认知（MySQL/PostgreSQL/openGauss 表级 FRAS）与 aoci ui 面板内嵌为后续里程碑。

安全说明

  • 凭据仅以环境变量名引用（AOCI_DB_<ID>_DSN）；插件从不存储或嵌入密钥。
  • aoci 二进制从官方 Release 下载并 SHA-256 校验；不捆绑、不分发（FSL-1.1-MIT）。
  • MCP/子进程环境在合并显式覆盖前会清洗形似凭据的变量。
  • 所有 /aoci/* 面板路由仅限 loopback。

致谢

  • AOCI-CODE 团队与《AOCI: Symbolic-Semantic Indexing for Practical Repository-Scale Code Understanding with LLMs》作者（arXiv:2605.02421）—— 受治理的认知范式与本地优先 MCP 服务器是本插件的基础。
  • DeepSeek Harness SDK 团队 —— 沙箱上下文与注入声明、ctx.tools、ctx.commands、__ModuleLoader__.load 前端契约等插件协议。
  • dsh-task-board（@linxin666/dsh-web-ui）与 dsh-better-sidebar（omdsh-dev/DSH-better-sidebar）维护者 —— 双面插件架构与清单协议的直接参照。
  • dsh-plan-mode（@deepseek-ai/dsh-plan-mode） —— ctx.inject(['commands'], …) 注册与 agent.steer 提交模式。
  • 早期试用者与审阅者 —— 真实环境反馈驱动了 0.1.x 修复周期。

完整版本历史与致谢见 RELEASE.md。

许可与归属

MIT License（见 LICENSE）。AOCI-CODE 采用 FSL-1.1-MIT（source-available，github.com/aoci-spec/aoci-code）；本项目不持有、不分发 AOCI-CODE 二进制。设计文档见 docs/DESIGN.md。