[返回项目介绍](../README.md)

# 使用与配置

面向 DeepSeek Harness 的长期 AI 伙伴与多渠道插件。

内置市场现提供可选的「影视创作工作流」和「导演与分镜设计」，包含离线参考资料、模板及许可证，按需读取，不默认给伙伴开启。详见 [影视创作技能](../docs/director-skills.md)。

新增 [伙伴 MCP 服务](../docs/mcp.md)，在页面集中配置 HTTP / stdio 服务，再按伙伴授权；授权和工具目录刷新在原会话下一轮生效。

伙伴不是一次会话中的临时提示词。每个伙伴拥有独立身份、Agent Preset、模型路由、能力声明。同一伙伴的本地、微信、Matrix、Mattermost 共用主对话；所有已授权联系人共享对话上下文，不适合作为多人隐私隔离的公共机器人。微信使用腾讯微信 iLink Bot API，不模拟个人微信网页版协议。

交互提问按实际消息来源返回，不按会话绑定猜测渠道。伙伴默认可修改自身 Matrix / Mattermost 渠道账号头像，无需单独开启能力，详见 [提问来源与渠道头像](../docs/channel-questions-and-avatar.md)。

Matrix / Mattermost 私聊支持图片、文件、音频和视频收发；单条入站消息最多 8 个附件、合计 64 MB。音视频先作为文件保存或交付，不自动转写；Matrix 加密房间仍不支持。详见 [渠道说明](../docs/direct-channels.md)。

## 当前能力

- 伙伴创建、编辑与删除
- 新伙伴只建立身份和本地会话；能力、长期记忆、每日回顾、心跳、渠道与伙伴间授权默认全部关闭
- Agent scoped 身份提示，仅影响该伙伴创建的 Agent
- 为伙伴选择 Agent Preset、提供方与模型
- 微信 iLink Bot 扫码连接
- `bot_token` 只保存到 DSH Credential Store，管理 API 和浏览器均不返回
- 微信渠道启用、停用、断线退避与运行状态
- 私聊首次联系配对审批
- 同一伙伴的本地、微信、Matrix、Mattermost 共用主对话；渠道身份用于来源路由，不是隐私隔离
- DSH Agent 完整回复后回发微信，并保留 iLink `context_token`
- 微信图片与文档双向收发：图片进入 DSH 原生附件上下文，文档安全保存到伙伴独立工作目录
- 伙伴可把工作目录内生成的图片、PDF、Office 文档及常用文本文件回发微信
- DSH 运行中发起选择题或自由提问时同步到微信；联系人回复序号、选项文字或自定义答案后，原 Agent 继续执行
- 微信在伙伴忙碌时遵循 DSH 全局 `ui-conversation.busyEnter`：`steer` 插入当前轮，`queue` 排入下一轮
- 按伙伴和微信联系人双重隔离的完整对话归档、每日回顾与结构化长期记忆
- 逐轮记忆提炼使用有界的专用上下文，只发送当前轮、相关记忆的精简视图与最近证据；每日终审保留当天每轮的双向代表片段，未进入提示的旧数据仍由存储层完整保留
- 从明确对话中形成可审计的联系人画像；可靠画像作为会话理解基线，偏好、任务、事件、关系与短期情绪信号继续按当前话题召回
- 人物画像按联系人隔离，使用固定长期槽位和证据阈值；用户可查看来源、手动修正或删除，已确认内容不会再被自动提炼覆盖
- 每日终审只保存有证据的记忆关系；强关系可把一跳关联记忆补入当前话题召回，并在关系审计中解释召回依据
- 冲突关系不会被合并成用户事实；仅在当前话题相关时提示伙伴指出差异并请求确认，所有关系仍严格按联系人隔离
- 对话提炼与每日终审会识别尚未闭环、反复不满意、采用临时方案或正在等待外部结果的「伙伴挂念」；长期记忆只提供理解背景，不直接生成巡检任务
- 伙伴会话额外提供一个紧凑的 `partner_concern_suggest` 候选工具；它只在伙伴自己的会话且长期记忆开启时可见，不会增加普通 DSH 会话的工具提示开销
- 工具候选和轮后提炼共用确定性准入策略：必须引用当前用户原话，满足优先级、置信度和综合分数门槛；每批最多新增两条，同主题只更新不重复创建
- 用户也可以自然地交代一件需要留意的事，并通过「继续留意、提高关注、已经解决、别管这个」控制它的生命周期；明确说出目标的“停止关注”会确定性更新状态，不依赖模型事后猜测
- 伙伴从记忆提炼或每日终审中自动新建关注后，会在当前伙伴会话中发出一次创建通知，并同步到对应的微信渠道，方便及时检查或移除
- 心跳只查询到期挂念，使用独立内存推理作用域观察上次检查后的变化；无到期事项时不会调用模型
- 心跳根据挂念选择当前可用的安全来源，并在来源内部逐层缩小范围：知识库按“找库→库内搜索→读取条目”，本地按“确定范围→定位文件/内容→读取证据”；发现阶段有独立软截止、单工具超时和整轮安全上限
- 关注可使用来源会话已有的 bash 工具完成文档要求的多步检查，保留 DSH 原有审批，不另行实现命令执行或自动授权。
- `@文件` 仅作为只读依据；记录写权限只覆盖用户在“需要记录的地方”手动选择的现存文件或笔记，不能创建其他文件或触碰伙伴私有存储
- 发现结果先保存为 Observation，经过去重、相关性、新鲜度、可行动性和近期打扰历史的确定性评分，再决定静默记下、下次顺手一提、进入伙伴动态或主动通知
- 心跳硬性排除伙伴记忆、挂念数据库、会话归档及其备份，不向无关主题扩散
- 未送达的重要提醒会保留并安全补发；普通对话开始时只召回与当前消息相关的延迟提及
- 每次实际巡察结束后在原伙伴会话写入一条可折叠的活动说明，便于核验工具、结果摘要、最终判断和通知状态，不生成伙伴回复气泡
- 可配置静默时段、检查间隔、每日通知上限、失败退避和手动检查；失败后不会早于正常检查间隔重试
- 修改伙伴身份或能力时清理该伙伴的渠道 Session，防止新旧人格串联
- Windows、macOS、Linux 兼容的原子状态写入
- 兼容 `SKILL.md` 的伙伴 Skill：安装与伙伴启用关系分离，支持在管理台创建本地 Skill、`inline` / `fork` 上下文、`allowed-tools` 权限收缩、校验和审计
- Skill 市场的“已安装 → 导入 Skill”支持本机 ZIP 和目录选择，完整保留脚本、参考资料与二进制资源。每次导入一个包含 `SKILL.md` 的技能，支持外层包装目录；最多 512 个文件、32 MiB 总量、单文件 8 MiB，`SKILL.md` 为 512 KiB。其他压缩格式请先解压。拒绝越界路径、链接、冲突文件及损坏压缩包；不会执行安装脚本或自动为伙伴启用，也不覆盖已有 Skill。
- 可信 `inline` Skill 的 `run` 会返回当前会话应应用的指令及资源目录，不再错误创建缺少伙伴工具的临时会话；只有 `fork` 使用隔离执行。内置分解 Skill 1.6.0 明确区分原生子 Agent 与持久化看板委派：重新设计、调研与可行性验证按真实产出进入同一需求，不能以临时并行研究替代看板分工。仍不新增前置 Skill 或全局工具门禁。
- 内置精选 Skill，以及与 nomifun 当前一致的 ClawHub、LoopHub、SkillHub 三个公开 Skill 榜单；支持统一 HTTP 代理、连接测试、受限 ZIP 安装与兼容 JSON 索引的团队源，非可信市场强制使用隔离临时会话
- 人与伙伴共享的任务看板：收集箱、待开始、进行中、待验收、受阻、已完成六个状态，带优先级、负责人、乐观并发 revision 与有界活动记录
- 有向伙伴授权和真实委派：在 A 的能力页勾选 B 后，A 才能查看 B 的公开能力并通过 `@B` 委派；用户本人可从全局看板直接指派任意伙伴，只共享任务信封、公开能力和结果摘要
- 伙伴会话内提供 `partner_skill`、`partner_task_board`、`partner_collaborate`、`partner_schedule`，以及按能力显式授权的 `partner_companions` 作用域工具，不污染普通 DSH 会话的工具表；“创建伙伴”工具只填写身份，新伙伴默认没有能力，后续由用户或已获高权限管理授权的伙伴配置
- 可单独授权 `partner_companion_manage`，管理其他伙伴的身份、能力、Agent Preset/模型、Skill、单向协作关系及知识库挂载；默认关闭，不能修改自己或转授本管理权限
- 伙伴定时任务支持间隔与每日时间、跳过或排队重叠、手动执行和重启恢复；每次使用新临时会话，完成后默认销毁，也可选择保留以便审计
- Skill fork、伙伴委派和定时任务共用同一个有界临时执行器，统一处理模型/预设组合、并发上限、超时、工具权限、运行记录与会话回收

心跳默认关闭，升级后不会突然主动发送消息。支持微信、Matrix 与 Mattermost 私聊，群聊策略尚未开放。

## 伙伴管理（高权限）

在目标管理者的「能力 → 高权限管理」中开启「伙伴管理（高权限）」。仅授予可信伙伴；普通协作勾选不等于管理授权。本能力可以配置其他伙伴，但不开放其私有会话、记忆、渠道或凭据，也不能授予或撤回 `administration` 本身。

开启后可直接交代：“把研究员的身份改成资料核验助手，使用研究预设，启用研究 Skill，允许访问核验员，并挂载项目知识库。”模型通过作用域工具 `partner_companion_manage` 执行：

- `catalog → inspect → update`：选择现有预设、模型、已安装 Skill 和伙伴，先读取 `revision`，再提交所需字段。未提供的字段不变；能力、Skill 和协作数组会替换对应列表，空数组清空。工具组合沿用 DSH Agent Preset，不直接修改全局工具权限。
- `knowledge_catalog → knowledge_inspect → knowledge_configure`：一次配置一个库，覆盖该伙伴默认项目及已有会话，让默认目录中的新会话也能继承。挂载设置是完整配置，省略项默认为开启召回、审核回写、空标签和空提取规则；停用使用 `enabled: false`，不删除知识内容。

知识库挂载要求同时安装包含 `dshKnowledgeMountManagement` 接口的知识库插件；旧版或未安装时会明确提示，身份、能力等管理仍可用。挂载通过知识库当前选中的本地或远程后端执行，远程只读令牌不能修改挂载，不会绕过认证或退回本地写入。

目标伙伴执行中拒绝管理工具修改，配置过期须重新读取。配置保存成功后，身份、能力、Skill 与协作关系在下一轮执行前注册，无需为了注入工具重开会话；Preset 和模型作为会话默认配置，不覆盖已有会话的选择。此权限不自动开启任何伙伴的记忆、心跳或渠道。

## 安装

```bash
dsh plugin --profile web add @lemoncat7/dsh-partner
```

本地压缩包：

```bash
dsh plugin --profile web add ./lemoncat7-dsh-partner-<version>.tgz
```

重启对应 DSH profile 后，左侧「空间」上方会出现「伙伴」。打开伙伴面板，创建或选择伙伴，再进入「微信」扫码。

## 默认配置

```yaml
- insert:
    - id: partner
      name: '@lemoncat7/dsh-partner'
      config:
        statePath: !!js dshHomePath('partner/state.json')
        exposeWeb: true
        apiPrefix: /partner-local/v1
        defaultCwd: ''
        autoStartChannels: true
```

`defaultCwd` 为空时使用 DSH 进程当前工作目录，以兼容桌面端和 Docker。可按部署情况显式设为真实存在的绝对路径。

## 微信流程

1. 插件请求 `/ilink/bot/get_bot_qrcode?bot_type=3`。
2. 页面每两秒检查二维码状态，确认后凭据直接进入 Credential Store。
3. 后台通过 `/ilink/bot/getupdates` 长轮询接收消息。
4. 未授权联系人只会创建配对请求。
5. 批准后，接入该伙伴共用的主对话。
6. 收到图片时，插件通过微信 CDN 下载并解密媒体，保存到伙伴工作目录，同时作为 DSH 原生图片附件交给 Agent；文档保存后以安全路径交给 Agent。
7. Agent 使用伙伴身份和所选 Preset 运行，最终文本通过 `/ilink/bot/sendmessage` 返回微信；回复中明确引用的工作目录文件会加密上传并作为微信附件发送。

渠道身份只决定消息归属，不授予任何工具权限。SSH、知识库和未来 Git 插件仍执行各自的挂载、授权和审批规则。

## 数据与安全

- 存储布局由持久化的存储版本决定；安装不会自动迁移。迁移后的公共数据位于 `dirname(statePath)/storage-v1/`，私有配置、记忆与关注位于 `<defaultCwd>/partners/<伙伴 ID>/.partner/`。旧布局和备份不能手动混用，详见[存储迁移](../docs/storage-migration.md)。
- 迁移先备份、校验再切换；迁移后不要直接降级。工作文件 `runs`、`inbound`、`task-results` 保留原位置，凭据仍由 DSH 管理。
- 敏感凭据：DSH Credential Store，scope 为 `dsh-partner-weixin`。
- 管理 API：默认 `/partner-local/v1`，仅接受同源请求；写操作还要求 `X-DSH-Partner-Request: 1`。
- 微信机器人只能绑定一个伙伴；同一伙伴的已授权联系人共享主对话上下文，不适合用作多人隐私隔离机器人。
- 入站附件上限为 64 MB，保存在 `<伙伴 cwd>/inbound/`，目录权限为 `0700`、文件权限为 `0600`。
- 出站附件最多 8 个，只允许伙伴工作目录内的真实文件；会解析真实路径并拒绝符号链接越界、未知格式和超限文件。

## 开发

```bash
npm install
npm test
npm pack --dry-run
```

要求 Node.js `^22.19.0 || >=24.0.0`，与当前 DSH 运行时一致。

新模块的依赖方向、隐私边界和持久化约束见 [`docs/architecture.md`](../docs/architecture.md)。

## Skill 市场索引

ClawHub、LoopHub、SkillHub 是内置公共来源，默认启用且不能删除。公共压缩包只会在内存中读取最浅层的 `SKILL.md`，不会把归档路径直接解压到磁盘；安装后按非可信 Skill 在隔离临时会话中运行。

自定义市场源返回 JSON 数组，或返回带 `skills` 数组的对象：

```json
{
  "skills": [
    {
      "id": "team-release-audit",
      "name": "团队发布审计",
      "description": "执行团队约定的发布前检查。",
      "version": "1.0.0",
      "tags": ["release", "audit"],
      "skillUrl": "./team-release-audit/SKILL.md",
      "checksum": "sha256:可选的64位十六进制摘要"
    }
  ]
}
```

`skillUrl` 可相对索引 URL。市场索引上限 1 MiB、单个 `SKILL.md` 上限 512 KiB；未标记为可信的市场即使声明 `context: inline`，安装后也会强制改为 `fork`。

市场页面的“代理设置”接受不含账号、密码和路径的 `http://host:port`。配置仅保存在当前客户端的伙伴状态中，同时作用于市场索引、Markdown Skill 和 ZIP 安装包下载；测试连接不会先写入配置。需要鉴权的代理应在本地网关侧处理，不要把凭据写进代理 URL。

## 关注依据与记录位置

关注使用后台轻量模型循环，不创建临时 Agent 或向聊天写入过程消息。每条关注独立执行，最多 12 轮工具交互和一轮无工具收尾，不再共用整批总时限或工具调用次数。单次模型请求最多 180 秒，单次工具最多 60 秒（工具自身可有更短限制），收尾有独立请求时间。每条完成立即保存；失败只保留未完成关注等待重试。只提供关联依据与记录目标，按文档完成代理、登录和查询；工具走来源作用域的 DSH 执行和审批，不自动批准。输出截断需按需分页。依据只读，结果仅写指定目标；检查受阻不能当作无变化。工具审计不复制参数正文。任意命令的文件隔离仍依赖 DSH 沙箱，工具名限制不等同文件系统隔离。

“交代一件事”中的 @文件或 @知识文档是只读检查依据；“需要记录的地方”另选现存本地文件或可编辑笔记。没有记录位置时不写文档，旧关注不自动把依据迁移成输出位置。有依据按依据整理，没有依据自主记录核实的现状和进展；笔记使用稳定 ID 绑定，知识库插件需提供 `dshKnowledgeNoteRecording` 宿主接口。心跳的笔记工具只接收 concernId，不允许模型选择其他笔记 ID；本地文件写权限只覆盖用户选择的现存文件。该入口不包含创建、删除、移动或重命名记录目标。首次可初始化已核实现状，后续避免重复追加，写入与通知判断相互独立。

完整核验结果通过 `heartbeat_record_checkpoint` 持久暂存，后台独立同步到记录目标。失败15分钟后仅重试同步，不重新抓取或提醒；实际写入成功才清除任务。详见 [1.14.0 发布说明](../docs/releases/1.14.0.md)。