HARNESS

DeepSeek 的 AI 产出物资产层。

DeepSeek 负责生成内容，HARNESS 负责发现、整理、管理、复用这些 AI 产物。

它不是一个独立软件，而是像 Finder 之于 macOS —— 用户感觉它一直在那里， 而不是「打开了另一个系统」。

它解决什么

你在和 AI 工作，AI 帮你做出了东西（一份方案、一份分析、一个规格）。 这些产出散落在工作区里，几天后你只记得「好像做过」，找不到是哪个文件。

HARNESS 做三件事：

1. 发现 —— 扫工作区，认出哪些是「AI 帮你整理好的文件」（而不是依赖、脚手架、源码）
2. 确认 —— 侧栏提示「发现新资产」，你点保存或忽略
3. 沉淀 —— 存进本地 Markdown 资产库，按项目/时间/类型/会话归类

产品形态

停靠在右侧 25%，对话区保留 75%。不做弹窗、不做 Dashboard。

┌───────────────────────────┬─────────────┐
│                           │  HARNESS    │
│                           │             │
│      DeepSeek 对话         │  发现区      │
│         (75%)             │  我的资产    │
│                           │   (25%)     │
└───────────────────────────┴─────────────┘

视觉方向：Finder / VS Code Explorer / Notion Side Peek。 安静的文档列表，不是管理后台 —— 无大卡片、无统计看板、无图标堆砌。 配色跟随 DSH 主题，浅色为主。

核心：资产发现评分

工作区里 90 个文件，真正值得沉淀的可能是 6 个。全收等于没收。

所以每个文件会打一个 0-100 的「AI 资产分」：

维度	分值
Markdown 结构（标题层级、正文段落）	+20
标题完整	+10
目录存在（≥3 个小标题）	+10
AI 语言特征（「以下是」「综上」「方案」…）	+20
来自工作区顶层	+30

新鲜度单独计，不进推荐分。 早期版本把「生成后已沉淀」当加分项， 结果和产品场景直接冲突：核心场景是「AI 刚帮我做完，我顺手沉淀」， 而那正是分数最低的时刻（刚生成 5 秒 = 55 分被 60 的阈值挡掉，要等 6 分钟才推荐）。 判断一份文件是不是 AI 产出，跟它是不是刚写的无关 —— 所以新鲜度只用于排序：

生成后	新鲜度
≤10 分钟	+15（最该被看到）
≤1 小时	+8
≤1 天	+3

硬性排除：node_modules/.git/dist、脚手架文件（package.json/README.md/ LICENSE）、凭据、图片/压缩包/源码 —— 这些直接判 0。

实测：/root/Deepseek 下 90 个候选 → 推荐 6 个，全是真正的 AI 产出文档。

自动出现

产品场景是「AI 刚帮我做完，我顺手沉淀」，所以不该等用户想起来点侧栏。

• 每 15 秒问一次发现区，有新产出就把侧栏展开
• 只展开侧栏，不弹窗、不抢焦点 —— 用户正在写作，打断比不提示更糟
• 用户手动收起后安静 5 分钟，不再自动弹出（尊重用户意图）
• 数量没变就不重复展开

资产状态

每份资产有一个状态：草稿 → 已确认 → 已归档。

• 自动采集/扫描进来的 = draft（草稿）
• 用户主动点「保存」的 = confirmed（已确认）
• 详情里可随时切换，侧栏只给非草稿显示标签（草稿是默认态，挂标签没信息量）

命名：内容优先

「AI 负责命名，用户只负责确认」 —— 标题优先取正文里的 H1，不是磁盘文件名：

情况	标题
文档有 H1	小米摄像头 fnOS 插件 — 项目设计文档（H1）
显式指定	用户/模型给的那个
代码/数据文件	文件名（首行是 const a = 1，当标题很怪）
文档无 H1	正文首个实文行
全空	文件名

deriveTitle 会跳过 YAML front matter，避免把 --- 或 title: xxx 当标题。

会话感知

侧栏会跟随当前会话：切换会话时，「当前会话」区列出的是那个会话沉淀的资产。

实现要点：DSH 的 ctx.uiSession 暴露 currentBinding.sessionId，外置插件要拿到它 必须在 package.json 的 dsh.client.inject 里声明 @deepseek-ai/dsh-client-ui-session（官方插件也是这么做的）。 DSH 没给客户端插件会话切换事件，所以客户端低频对比一次，变了就通知面板重拉。

拿不到会话 id 时退回「全部资产」视图，不报错。

Markdown 阅读器

详情里直接渲染标题 / 列表 / 代码块 / 表格 / 引用 / 链接，不再是 <pre> 原文。

长文档有目录：标题 ≥4 个时自动生成可折叠目录，点击跳转。

目录 · 41 节
  MiCam 开发笔记（cs2 直连踩坑全记录）
    一、go2rtc 使用要点
      1.1 Dial 内部已完成握手
      1.2 Producer 是推模式，必须有人读

实测 546 行的真实文档生成 41 条层级目录。细节：

• 标题生成唯一锚点 id（中文保留，重名自动加序号）
• 影子树里 #anchor 跳转不生效（浏览器只查文档级），所以点击是手动 scrollIntoView
• 短文档（<4 个标题）不给目录，免得啰嗦

自己写（lib/markdown.js），不引外部依赖 —— 引 marked / markdown-it 会给插件 加一棵依赖树和一个构建步骤，违背「dependencies 为空」的铁律。

安全：文档内容是不可信输入。渲染前全部转义，链接只放行 http/https （javascript: / data: / vbscript: 一律降级为纯文本）。 13 个 XSS 向量在测试里覆盖（script / img onerror / svg onload / iframe / 属性注入 / 大小写绕过 / 表格与引用内注入…）。

视觉方向

不要：Dashboard、大卡片、数据统计、图标堆砌、深色科技风、抽屉弹出动画。

要：原生集成、极简侧栏、文档列表、AI 发现提示、小而精致、像系统功能。

右侧面板 300ms 平滑出现（macOS Finder 侧栏的手感）， 能停靠就停靠进 AppFrame 的右栏，停靠不了才退化为固定定位。

📦 安装

dsh plugin --profile web add /path/to/dsh-asset-library
# 重启 dsh web 生效

要求 pnpm 在 PATH 上（没有就先 corepack prepare pnpm@latest --activate）。

装完侧边栏会出现「素材库」入口，点开是管理页；也可以直接访问 <dsh web 地址>/ext/asset-library/。

🗂 数据长什么样

<DSH_HOME>/asset-library/
├── time/2026-09/
│   └── 2026-09-14-接口设计稿-3f9a2b.md
├── type/markdown/
│   └── 2026-09-13-读后笔记-a1b2c3.md
└── session/素材库开发-c7b1b0f9/
    └── 2026-09-13-会话结论-9d8e7f.md

每个 .md：

---
id: "ast-c500f747-..."
title: "项目轴验证"
kind: "file"
axis: "time"
created: "2026-09-14T01:26:25.013Z"
session_id: "session-5549d9ae-..."
session_title: "素材库开发"
source_path: "/root/Deepseek/dsh-asset-library/lib/store.js"
file_type: "javascript"     # 细粒度类型名
category: "code"            # 语义类别（类型轴的桶）
project: "素材库插件"        # 项目维度
tags:
  - "代码"
  - "dsh-asset-library"
summary: "项目归类测试"
---

项目归类测试

手写友好：直接把一个自己写的 .md 丢进库目录，下次载入就会被索引； 缺 front matter、字段残缺都不会报错。

📥 导入历史会话

面板顶栏的**「导入历史会话」**按钮，把 DSH 已有的会话日志提炼成素材。

不是原样倾倒 —— 你机器上 6 个会话有 8000+ 个事件，全量入库只会是一堆噪音。 提炼规则（lib/session-import.js）：

来源	产出
每个会话	一条会话纪要（标题、轮次、提问数、产出数、前几条提问）
会话产出的文件（write/edit 等）	逐条登记为 file 素材，带真实路径
助手回复中 > 200 字的结论	单独存为 note

实测：8125 个事件 → 91 条素材。

几个刻意的取舍：

• 只认人真正敲的消息（source.kind === 'user'）当提问与标题 —— 会话日志里混了大量插件注入内容（工具结果回灌、审批策略通知、技能目录），拿来当标题会很难看
• reasoning 块不入库 —— 那是模型的思考过程，不是结论
• 重复导入会跳过已导入的会话（也可强制重扫）
• 推不出项目名时回落到会话标题，而不是编一个名字

会话日志是多帧 zstd（每次写入追加一帧，单文件可达上千帧）， zstdDecompressSync 只解第一帧。必须按 magic number 切帧逐帧解压。

⌨️ 斜杠命令

在会话输入框里直接敲，不进入模型请求，立即执行：

命令	作用
/save	保存上一条助手回复（标题自动从正文首行推导）
/save <标题>	同上，但用你给的标题
/save note <正文>	把 <正文> 直接存为笔记
/save list [关键词]	列出素材，可按关键词过滤
/save help	用法

🤖 模型工具

工具	用途
asset_save_file	保存一个文件（文本会内联正文；二进制/超大只登记路径）。同路径重复保存自动去重
asset_save_snippet	直接保存一段文本/结论/代码，不依赖磁盘文件
asset_list	列表 + 过滤（axis + bucket，或 project，或关键词 q，或 kind）
asset_overview	总览：三轴各有哪些桶、各多少条
asset_read	读一条素材的全文

🔌 HTTP API

方法与路径	说明
GET /ext/assets/views	三轴视图（桶 + 计数）
GET /ext/assets/list?axis=&bucket=&q=&kind=&limit=&offset=	列表
POST /ext/assets/register	登记一条素材
GET /ext/assets/<id>	元数据
GET /ext/assets/<id>/content	元数据 + 全文
GET /ext/assets/<id>/file	下载那个 .md
PATCH /ext/assets/<id>	改标题/摘要/标签/正文
DELETE /ext/assets/<id>	删除条目与文件
GET /ext/asset-library/	管理页

安全边界：webServer 本身没有鉴权中间件，而 profile 可能绑到 0.0.0.0 供局域网访问。因此所有写操作、以及与文件正文相关的读取，仅限回环来源 （判据是 TCP 层的 socket.remoteAddress，不可伪造）。非本机来源只拿到不含正文的只读元数据。

⚙️ 配置

在 profile 的 cordis.patch.yml 里覆盖（全部可选）：

- id: asset-library
  config:
    rootDir: /your/library        # 默认 <DSH_HOME>/asset-library
    autoCollect: true             # 默认 true
    maxPerTurn: 20                # 单轮自动采集上限
    mutationTools: [write, edit]  # 视为「文件变更」的工具名
    maxInlineBytes: 262144        # 超过就不内联正文，只登记路径

🧱 为什么 dependencies 是空的

这不是洁癖，是一个踩过的坑。

DSH 的模块解析会优先命中 ~/.dsh/profiles/<name>/node_modules，遮蔽 /opt/dsh/.../node_modules 里的宿主版本。如果一个插件在自己的 dependencies 里写了宽松范围的 @deepseek-ai/*，pnpm 很可能装进一个与宿主版本不匹配的副本， 然后整棵 agent 树就启动失败。实测中 dsh-artifact-library 就是这样让 dsh web 起不来的：

SyntaxError: The requested module '@deepseek-ai/dsh-llm'
  does not provide an export named 'CallId'

所以本包：

• dependencies / peerDependencies 全空；
• 不 import 任何 @deepseek-ai/*；
• DSH_HOME 自己解析（lib/paths.js），工具定义手写（不用 defineTool）；
• 宿主能力全部通过 ctx 服务在运行时取用（tools / webServer / systemPrompt）， 用 ctx.inject 惰性挂载 —— headless profile 里没有 webServer 也不会挂。

装完可以自查：ls ~/.dsh/profiles/web/node_modules/@deepseek-ai 应该是空的。

🧪 测试

npm run smoke              # 九套一起跑
npm run smoke:markdown     # 34 项：Markdown 渲染 + 13 个 XSS 向量
npm run smoke:content      # 37 项：语义分类、标题/摘要/标签推导、项目推断
npm run smoke:artifact     # 22 项：资产评分、新鲜度分离、排序
npm run smoke:import       # 24 项：多帧 zstd 解压、会话提炼、重复导入跳过
npm run smoke:host         # 51 项：front matter 往返、四轴分桶、原子写、查重、搜索、分页…
npm run smoke:tools        # 用 DSH 真实 ToolRuntime 校验 5 个工具的 schema
npm run smoke:commands     # 30 项：/save 各分支、助手回复提取的防御式兼容
npm run smoke:http         # 19 项：每个路由的状态码/内容类型/安全边界
npm run smoke:ui           # 35 项：jsdom 真实文档 —— 可见性、几何、会话切换（需 jsdom）

smoke-tools 需要能找到 DSH 安装目录（默认 /opt/dsh/lib/node_modules/@deepseek-ai/dsh）， 用 DSH_ROOT 覆盖。

⚠️ 已知限制

• 侧边栏入口是 DOM 注入的。DSH 目前没给外部插件开放 sidebar.panellist 槽位 （共享模块表里没有 dsh-client-ui-sidebar），社区插件（link-collect、 skill-explorer、dshmarket）走的都是同一条路：注入一行 DOM + MutationObserver 自愈。 管理页因此是独立整页，不是原生的 main 面板。等官方开放后可平滑替换这一层。
• 没有文件系统监听。库目录被外部改动后，需要点管理页的「刷新」（或重启）才会重新索引。
• 正文内联有上限，二进制文件只登记路径与元数据，不在页面里预览。

📄 License

MIT