# 社区与平台调研记录

这份记录说明了插件开发前核对过的规范和社区实践（2026-09-01 核验）。
DeepSeek Harness 仍处于 developer preview 阶段，因此保留链接，便于未来
重新审计。

## Harness 官方契约

实现按 `dsh-v0.1.2-alpha.4` developer preview（commit
`4e84901e6471b79ec0338099867ebb4606d12bb5`）和 Node `22.19+`/`24+` 核对；
此前的 alpha.3 commit `dd6322d604e00eec1ba5e0c8541159906a21094a` 仍受支持。
这些都是验证基线，不代表长期 API 稳定承诺。

- [第一个插件](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/user/develop/basic/index.md)：插件导出 `name`、可选的 `inject` 和 `apply(ctx, config)`；通过 Cordis 注册的贡献会随插件 fiber 自动释放。
- [插件配置](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/user/develop/basic/config.md)：接受配置时应导出 Schemastery `Config` schema。
- [打包与安装](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/user/develop/basic/publish.md)：可安装 bundle 需要 `type: module`、`main` 和 `dsh.bundle.patch`；补丁用已安装包名插入插件行。
- [工具开发参考](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/cookbook/adding-a-tool.md)：规定模型工具 schema、规范化 JSON 返回值、有限渲染、`exec.signal` 取消和 `agent.inject` 接口。
- [Agent 运行时类型](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/core/agent/src/runtime-types.ts)：公开 `agent/status`（`idle`/`running`）和 `agent.runMaintenance()`。本插件只把 idle 作为防抖触发，不把清理操作插入模型回合。

## 调研过的社区项目

| 项目 | 可借鉴实践 | 本 MVP 的边界 |
| --- | --- | --- |
| [dsh-tidy-organizer](https://github.com/LzqSuShi/dsh-tidy-organizer) | scan → plan → apply → undo、JSONL 审计、重名安全移动、适合 plain JS 的打包方式 | 其桌面/下载目录的广泛分类不纳入本插件的窄 managed roots |
| [workspace-metabolism](https://github.com/metabolism-tools/workspace-metabolism) | policy-driven audit/recycle/rollback 词汇，状态放在工作区外 | 不提供无边界或误触发的 purge；自主执行必须显式开启，不运行全局 daemon，也不做不透明策略推断 |
| [dsh-plugin-development](https://github.com/w2112515/dsh-plugin-development) | 极简 ESM `index.js`、`dsh.bundle`、隔离 profile 验证 | 本插件额外提供 Schemastery 配置和模型工具 |

这些项目只是设计参考，并不是运行时依赖；其 API 可能发生变化。

## 从调研得到的实现决策

1. 首版使用原生 JavaScript，避免 Git 安装时隐式执行 `prepare` 构建。
2. bundle 只插入一个稳定的 `workspace-hygiene` 行，用户可在 profile 中整体覆盖配置。
3. 手动写操作采用两阶段：只读计划、短期 token、显式确认和二次校验；全自主模式
   仍生成同样的哈希绑定计划并执行二次校验，只把显式自主配置作为确认边界。
4. 将 `workspace-artifacts/` 设计为元数据目录，而不是文件仓库。四个分类目录
   只保存源文件的相对路径、目录、名称、用途和处理建议；源文件默认保持原位。
   归档/删除需要的可恢复副本、状态和审计记录仍放在专用隔离区和运行记录中。
   `to-delete` 条目只有在用户确认（或显式开启的自主策略授权）、且再次通过路径/保护/
   指纹校验后才会删除源文件，成功后同步移除条目。
5. 提供显式的 `autonomousMode`，让研究者选择是否在 idle 维护周期自动执行符合策略的
   决定；物理移动/重命名还需要 `valuePolicy.organization.moveFiles: true`，永久删除需要
   删除许可。该模式默认关闭，且不能绕过硬保护、managed roots、预算和指纹校验。
6. 面向模型返回紧凑结构化 JSON，完整清单留在 catalog 或通过 `limit` 有界返回，降低上下文压力。

## 本次重构的边界

catalog 的存在不意味着项目目录会被强制重排。手动模式只建立和更新索引，用户
可以逐项确认建议；全自主模式是 idle 维护自动执行符合策略建议的显式开关。物理
移动或重命名源文件还必须设置 `valuePolicy.organization.moveFiles: true`，永久删除
仍受删除策略许可约束。因此，评估“治理后”的效果时，应分别记录元数据维护收益和
物理组织收益，不能把两者混为一次不可解释的批量搬移。

## 安全提示

Harness 插件是受信任的同进程代码。安装后它继承宿主进程的文件系统权限；请审阅源码、固定 Git commit，并使用隔离 profile。普通工具审批不会为插件实现代码提供沙箱。