前言¶
在 DeepSeek Harness 里做架构梳理或流程说明时，常见做法是留在 Markdown 里画 Mermaid，或切到外部绘图工具再贴截图。前者交互弱、难和仓库证据对齐；后者和当前会话脱节，改一版就要重新导出。apitu 是面向 DSH 桌面的客户端插件：由当前会话里的模型读源码或需求、写出符合 schema 的 JSON，插件在本地渲染成交互式 HTML，并提供中文右侧栏与原生工具 apitu，不另配模型账号或 API Key。
这是什么¶
apitu（仓库 yueyexiayu/dsh-apitu，社区目录 skillhub.cn/plugins/yueyexiayu/dsh-apitu）由维护者 yueyexiayu 发布，分类为客户端。当前插件包版本为 1.2.4（MIT），内置图表核心标识 3.1.0（vendored 上游来源标识，带本地缺陷修复，不冒充上游新发行版）。一句话定位：把当前会话中的想法、需求或代码证据制作成交互式 HTML 图。
核心功能¶
下面介绍插件已文档化的能力边界，避免和旧 viewer 或独立 Mermaid 服务混淆。
六种图类型¶
支持 roadmap、architecture、workflow、sequence、dataflow、lifecycle。其中默认 roadmap 使用 api-sheji 风格中文双 SVG 站点地图（缩放/平移、F/A 编号、点击提示、路线筛选与流动光点等），不含旧 viewer 的主题、搜索、演示或 PNG/SVG/WebM 导出；其余五型仍保留主题、搜索、关系追踪、演示和导出。Roadmap 规范与示例位于包内 vendor/core/references/roadmap.md、vendor/core/schemas/roadmap.schema.json 等路径。
对话工具与 CLI¶
Host 侧通过 JSON 动作调用，例如 guide 返回创作入口与 skill 正文；read 按 offset 分页读 schema；run 在指定绝对项目目录下执行 CLI（如 finalize 走 validate → deliver → check → browser-check）。Mermaid、自然语言或仓库证据由当前 AI 阅读 skill 并转换为 typed JSON，不是独立 Mermaid CLI 或额外模型服务。
CLI 子命令包括 render、compare architecture、deliver、finalize、preview、validate、migrate workflow、inspect architecture|roadmap、check、browser-check、visual-check、guide、examples、doctor、demo 等；核心入口为 vendor/core/bin/apitu.mjs。preview 为本机持续预览，修改 JSON 可热更新；成功构建的 HTML 经大小与 SHA-256 核对后进入任务产物列表。
侧栏与文件策略¶
右侧栏选择 apitu，填写项目绝对工作目录。侧栏关联当前存活会话，由 Host 查询真实会话并应用与对话工具一致的文件策略，不接受前端指定策略模式。默认 roadmap 可生成六类示例、渲染已有 JSON、查看本会话任务结果并打开 HTML。
CLI 子进程不能继承受限 DSH 文件沙箱，仅在 danger-full-access 策略下执行；只读与 workspace-write 等模式会明确拒绝。读取插件内文档不受此限制。
安装与启用¶
当前执行策略接入版为 1.2.4。本机按 profile bundle 加载（package.json 的 dependencies + dsh.profile.bundles），包内 patch 的 name 为 apitu。修改后需 完全退出 DeepSeek Harness 后重新打开；重启后用工具 guide 或侧栏 GET 确认 version: "1.2.4" 再验收。
先做 clone，再做 profile 依赖与安装：
export DSH_HOME="${DSH_HOME:-$HOME/.dsh}"
git clone https://github.com/yueyexiayu/dsh-apitu.git "$DSH_HOME/plugins/apitu"
然后把 apitu 写入 $DSH_HOME/profiles/desktop/package.json 的 dependencies（link: 到该目录）和 dsh.profile.bundles，在 profile 目录执行 pnpm install，完全退出后重开 DSH。不要再对同一 id 做 desktop insert。
需要 finalize、浏览器或视觉检查时，在本插件目录安装固定无头依赖（Node.js ≥ 18，文档示例使用 /usr/local/bin/node；浏览器侧依赖 playwright-core@1.58.2）。兼容性说明：目前文档写明 macOS arm64 有经过验证的安装校验 manifest；Linux、Windows 等为 unsupported/unverified，安装前请自行核对 README「运行环境」一节。
典型用法¶
- 在对话中说「用 apitu 给这个项目画架构图」或「用 apitu 画订单支付流程」。当前会话模型负责读源码/需求、生成符合 schema 的 JSON，再调用插件。
- 右侧栏选择 apitu，填写绝对工作目录，按需选
roadmap或其它类型。 - 需要交付物时，先用 DSH 文件工具写好 JSON，再调用
run（目录仅为示例）：
{
"action": "run",
"cwd": "/absolute/project",
"args": ["finalize", "architecture", "candidate.json", ".apitu/new-run/diagram.html", "--json"]
}
自动检查通过不等于人工视觉检查通过；ok:false、非零 exitCode、stderr 或 receipt gate 失败时必须修复后再交付。失败或视觉修复后应重跑完整 finalize，使用新产物路径（例如 .apitu/new-run/repair-2/diagram.html），只改 --out-dir 不够。
查规范时可从工具入口分页读取：
{"action":"guide"}
{"action":"read","resource":"schemas/architecture.schema.json","offset":1,"limit":180}
适用场景与注意¶
适合在 DSH 桌面里和当前会话联动：架构图、工作流、时序、数据流、生命周期和 roadmap 站点图，产物为本地 HTML，可在侧栏打开。
务必注意：
- 插件以当前 DSH 进程权限运行；安装前应阅读仓库源码与 MIT 许可证，确认
danger-full-access与本地文件写入范围可接受。 - 普通任务最多运行 180 秒，输出上限 2 MiB；持续 preview 另有并发与保留策略（文档：最多 8 个活动预览等）。
cwd须来自真实会话目录或用户显式填写，仅支持本地文件系统。- 社区目录 skillhub.cn 为独立站点，与 DeepSeek / 幻方无官方从属关系；星标等元数据以目录页为准（当前为 0）。
结尾¶
apitu 把「会话里的结构化描述 + 本地校验与渲染」收进一个 DSH 客户端插件：中文侧栏、原生 apitu 工具、六种 typed 图与可选 headless 验收链。进一步细节见 GitHub README 的「完整能力与边界」「执行策略」「运行环境」各节，以及目录页 yueyexiayu/dsh-apitu。
