DeepSeek Harness Bundle · 项目无关的 AI 协作层

让每个 AI 会话,
接着上一棒继续

dsh-ai-collab 在仓库里放下两样东西:一个所有工具共用的 AGENTS.md,和一个只追加、可校验的 .ai/ 工作记录层。 项目事实、当前进度、历史决策,从此只有一份。

  • 数据只留本机
  • 无需联网
  • MIT 许可
  • Windows 10 / 11
5个
原生工具
3条
命令开始交接
0次
网络请求
100%
数据本地留存

01 · 问题

每个新会话,都在重新认识同一个项目

多 AI 工具协作时,最贵的成本往往不是写代码,而是让每个新会话重新理解项目——构建命令、烧录地址、只读目录、上次改到哪、为什么这样改。

01

重复交底

构建、烧录、编码约定散落在聊天窗口与个人笔记里,换一个工具就要重讲一遍。

02

进度断层

上一个会话的结论只活在上下文里;窗口一关,项目就回到「未读」状态。

03

工具割裂

DSH、Claude Code、Cursor、Copilot 各记各的,没有一份共同的事实源。

04

改动无账

改了什么、怎么验证、下一步是什么,只剩人的记忆和零散的提交说明。

最贵的不是写代码,而是让每个新会话重新理解项目。交底、记账、校验本来就要做——插件只是把它们变成仓库里的文件,而不是会话里的消耗品。

02 · 机制

一个入口,一层协作层

它不改变工程结构,只在项目根增加两样东西。AGENTS.md 负责「说清楚」,.ai/ 负责「记下来」。

AGENTS.md

唯一入口

所有工具开工先读:项目事实(构建、烧录、只读目录、编码约定)与固定动作(开工读什么、收工写什么)。纯文本、可 diff、可评审。

  • DSH、Cursor 3.x、Copilot 原生读取
  • Claude Code / Gemini 可一行转发
  • 分 generated 与 user 两区维护

.ai/

协作层

追加式日志、当前状态快照、版本级变更、schema 与归档。所有写入经由 .ai\llm.cmd 或 5 个原生工具,编码与格式由脚本保证。

  • log.jsonl 只追加,不改写
  • status.json 覆盖式,10 秒接手
  • changelog/ 存根因、数据与补丁
  1. STEP 1开始会话任意工具进入项目
  2. STEP 2读 AGENTS.md事实、约束、固定动作
  3. STEP 3status + tail当前阶段与最近十条
  4. STEP 4执行并 add一行记录,带验证结果
  5. STEP 5check 后交接下一个工具从文件接手

与语言、框架、IDE 无关:嵌入式固件、桌面应用、脚本仓库、文档工程共用同一套协议。

03 · 统一进度

同一份事实,同一份历史

工具可以换,入口不变。每个工具开工前读同一份快照,收工后写同一条流水;人也不例外。

工具接入方式参与方式
DSHBundle 安装,5 个原生工具ai_status / ai_log / ai_check 直接读写
Claude Code用户级 CLAUDE.md 转发,或 entries -Publish读 AGENTS.md,用 llm.cmd 记录
Cursor / Copilot原生读取 AGENTS.md继承项目事实与纪律
Codex / 其他 CLI任意 shell 调用 .ai\llm.cmdstatus / tail / add / check
人同一条命令tool: human,决策与验收也入账
01 开工≈ 10 秒

先读状态

status 与 tail -N 10:当前阶段、焦点、阻塞、下一步,以及最近十条记录。

02 收工1 条记录

追加流水

add 自动生成 id 与时间戳,刷新 status.json,并在需要时刷新看板与 TASKS.md。

03 提交前强制

校验记录

check 检查必填字段、枚举、时区、时间单调与 id 唯一,可选扫描敏感信息。

换工具不换进度,换会话不换上下文。

04 · 本地记录

记录留在本地,半年后还能追溯

聊天记录会消失,仓库里的文件不会。每次工作被压成一行可校验的 JSON,「当前状态」与「版本级细节」分开存放。

Append-only · log.jsonl

只追加,不改写

UTF-8 无 BOM、LF、一行一个 JSON 对象。写错就追加一条 correction,用 corrects 指向原记录;历史行永不修改或删除。

Snapshot · status.json

覆盖式状态快照

phase、focus、blockers、next、last_log。新工具先读这一份,不必翻完整本流水。

Changelog · changelog/

版本级细节

根因、实测数据、补丁与已知限制。日志里的 summary 用 refs 指过去,不把单条记录撑大。

Validate · ai_check

结构可校验

必填字段、枚举、时区、ts 单调、id 唯一;超过 2 MB 或每季度归档到 _archive/,历史仍可检索。

{
  "id": "20261120T013921289-a3a5b4",   ①
  "ts": "2026-11-20T09:39:21+08:00",  ②
  "tool": "deepseek-harness",
  "actor": "ai",
  "action": "fix",                   ③
  "status": "ok",
  "summary": "修正 DMA 环形缓冲边界,rebuild 0/0",  ④
  "files_modified": ["src/uart_dma.c"],
  "verification": "rebuild 0/0, Code=124476",  ⑤
  "refs": [".ai/changelog/2026-11-20-uart-dma.md"]
}
  • ①唯一 id,供 correction 引用
  • ②ISO-8601 带时区,时间必须单调
  • ③status 五态;blocked / failed 必填 issue
  • ④一句话结论:做了什么 + 结果
  • ⑤怎么验的,以及细节在哪
一行记录谁、何时、做了什么
状态快照现在到哪、卡在哪
版本变更为什么、怎么验证
季度归档历史仍可检索

目标只有一个:任何时候都能回答——谁做的、改了什么、怎么验的、下一步是什么。

工作记录不出工作区。插件不发起网络请求、不写注册表、不接触凭据;敏感值放 .ai/private/,文档只写键名。任务清单在插件进程内渲染,克隆来路不明的仓库并记录日志,也不会执行仓库里的脚本。

05 · 分区设置

模板管纪律,项目管事实

AGENTS.md 被两条标记切成两个区。插件升级时只重写 generated 区,项目事实与区外内容逐字节保留。

AGENTS.md generated + user
generated 区 · §2–§7 模板维护 · 升级时重写

开工 / 收工固定动作、目录与权限表、构建与验证、硬性约束、领域文档索引、多工具入口。

  • 开工 / 收工固定动作
  • 目录与权限表
  • 构建与验证方式
  • 硬性约束与编码规则
  • 领域文档索引
  • 多工具入口与转发

<!-- dsh-ai-collab:generated:end -->   <!-- dsh-ai-collab:user:start -->

user 区 · §1 及之后追加 项目维护 · 逐字节保留

项目名、根目录、MCU / 工具链、版本控制、日志位置,以及采样数据、分析方法、硬件与协议约束、决策记录。

  • 项目名与根目录
  • MCU / 工具链
  • 版本控制与日志位置
  • 采样数据与采集过程
  • 硬件 / 协议约束
  • 决策与验证结论

实际文件由 HTML 注释标记分隔;上方两个区之间同时出现 generated 区的结束标记与 user 区的开始标记,文件末尾是 user 区的结束标记。

分区规则

场景行为
重渲染范围只替换 generated 区;user 区与区外内容逐字节保留
其它状态文件placeholders.json / log.jsonl / status.json 一律不动
无分区标记的文件视为项目自有文件并冻结(含旧格式单行标记);参考渲染只写 .ai\AGENTS.generated.md
显式迁移-ForceAgents:旧内容整体迁入 user 区,不删除;-ResetAgents:丢弃旧内容,破坏性

分区也发生在项目之间:每个仓库的 .ai/ 只属于自己;兄弟项目共享的 board.md 只读汇总,不反写任何项目的记录。

升级不再意味着「重新生成一份 AGENTS.md,再手工补回项目事实」。同一份 generated 区里还有 §3 权限表,把「哪些路径可写」也变成可评审的约定;user 区则由项目长期维护。

06 · 全局纪律

全局纪律,随每个会话加载

插件附带用户级纪律模板 AGENTS.global.template.md:复制到 $DSH_HOME/AGENTS.md(已有全局文件则合并),DSH 会在每个会话注入它——不依赖模型记性,也不依赖项目是否已经接入。它是可加载的:改一次文件,之后每个会话都带着同一套纪律开始。

01 · 安装$DSH_HOME/AGENTS.md跨项目纪律,一份文件
02 · 注入每个新会话DSH 启动时自动加载
03 · 第 0 步ai-ensure接入 / 升级 / 刷新,幂等
04 · 落地项目 AGENTS.md + .ai/事实与记录各归其位

全局文件只放跨项目纪律,没有任何项目事实。项目事实留在 <项目根>/AGENTS.md。编辑全局文件对下一次请求立即生效,无需重启;插件代码升级才需要重启 DSH。

00

第 0 步 · ai-ensure

每个会话先保证接入与同步:缺骨架则生成、模板过期则升级、看板过期则刷新。临时或系统目录返回 not-project,不强行接入。

01

先对齐,再动手

动手前给出本轮目标、待定项、方案与取舍;确认后执行。纯只读查询例外。

02

日志归属与看板边界

详细记录只留在各自项目的 .ai/;跨项目看板只读汇总,禁止反写项目内容。

03

默认只读与权限确认

工程文件默认只读;写未列出的路径,先说明原因与影响范围,确认后更新权限表再动手。

04

三步工作法

status + tail 开工,add 收工,check 校验。没写记录 = 这件事没做完。

05

事实与模板同步

generated 区归模板,user 区归项目;重渲染只替换 generated,事实逐字节保留。

06

硬性边界

临时目录、只读目录、工作区之外不接入;凭据、内网地址、客户信息不进日志。

07

记录质量

summary 写「做了什么 + 结果 + 验证方式」;根因、数据与补丁放 changelog,用 refs 指过去。

层级文件放什么维护者
用户级$DSH_HOME/AGENTS.md跨项目纪律,无项目事实用户 / 模板
项目级<项目根>/AGENTS.md项目事实 + 纪律路由generated 模板 + user 区
证据级.ai/log.jsonl 等每次工作的流水与验证所有工具与人
# 首次:把模板复制到 DSH 用户目录(已有全局文件则合并,不要直接覆盖)
Copy-Item "<包目录>\AGENTS.global.template.md" "$env:DSH_HOME\AGENTS.md"

07 · 快速开始

三条命令,开始交接

安装一次,之后每个会话只重复三个动作:读状态、干活、写记录。

A

插件管理器

推荐。选择本包绝对目录即可。

plugin_manager
  action: install_bundle
  target: <包绝对路径>
B

命令行

npm 包名或本地目录均可。

dsh plugin --profile <profile> add dsh-ai-collab

# 或本地目录
dsh plugin --profile <profile> add "<包绝对路径>"
C

profile patch

仅开发调试;生产安装走 bundle。

- insert:
    - id: ai-collab
      name: dsh-ai-collab
      config:
        autoInit: true

安装后重启 DSH;profile 内所有会话都会出现 5 个工具。首次进入某个项目时,先调用 ai_init(或把 autoInit 设为 true)生成 .ai/ 与 AGENTS.md,之后按下面的动作循环。若包只进了依赖、未进 dsh.profile.bundles,需要手动补一行。

# 开工:同步并读状态(约 10 秒)
& .ai\llm.cmd status
& .ai\llm.cmd tail -N 10

# 收工:追加一条记录,然后校验
& .ai\llm.cmd add -Tool deepseek-harness -Action fix -Status ok `
  -Summary "修复 UART DMA 丢包,验证:rebuild 0/0" `
  -Verification "rebuild 0/0, Code=124476"
& .ai\llm.cmd check
ai_status读状态与最近记录
ai_log追加一条记录
ai_check校验日志与状态
ai_board跨项目只读看板
ai_init幂等接入工作区

常用命令

命令作用何时用
status当前快照 + 最近记录开工第一步
tail -N 10最近 N 条流水快速回看上下文
add追加一条记录收工时;自动刷新 status 与看板
check校验格式、枚举、时间、id、敏感信息收工必跑
board刷新跨项目只读看板父目录存在 .ai\board.md 时
entries -Publish / -Remove生成 / 收回 Claude、Gemini 转发文件工具不认 AGENTS.md 时
archive归档旧日志到 _archive/超过 2 MB 或每季度
doctor环境与文件自检接入异常时

配置项

配置默认含义
autoInitfalse会话创建时对工作区跑 ai-ensure(排除临时 / 系统目录)
maxTail10ai_status 返回的最近记录条数
initScript包内 ai-ensure.ps1覆盖接入脚本(调试用)

08 · 边界与状态

已发布,边界清晰

0.4.4 已上 npm 并被社区插件市场收录;脚手架目前仅支持 Windows,只读工具与任务渲染本身与平台无关。

npm已发布
dsh-ai-collab@0.4.4 2026-11-20 上架,可直接安装
GitHub已就绪
ZhuYw3927/dsh-ai-collab 仓库与 tag 已推送,CI 可用
社区市场已收录
PR #16419 已合并 2026-11-19 收录;详情页与目录条目可访问
format-1 索引待重建
每日 catalog 构建 下一次构建后进入索引,仅影响索引源用户

兼容性

兼容性要求
DSH0.2.1+(在 0.2.2-rc.3 上实测)
Node.js>= 20;DSH 内置 Electron Node 可用
操作系统Windows 10 / 11;包声明 "os": ["win32"]
网络 / 凭据都不需要;数据只写工作区与本地日志目录
许可证MIT;另附 免责声明 与 建议性非商业声明(不改变 MIT 权利)
  • 1脚手架仅 Windows。macOS / Linux 返回 unsupported-platform;只读工具与任务渲染本身不依赖平台。
  • 2尚未导出 Config schema。配置在进程内归一化,非法值写入 ai-collab-config.log,不会静默沿用。
  • 3旧 AGENTS.md 被冻结。无分区标记的文件不会自动升级,需显式 -ForceAgents 或 -ResetAgents。
  • 4看板依赖目录布局。仅当兄弟项目共享父级 .ai\board.md 时生成跨项目看板。
  • 5生效时机不同。插件代码改动需重启 DSH;全局 AGENTS.md 编辑对下一次请求立即生效。

下一步:跨平台 Node 脚手架 · 导出 Config schema。市场详情页:awesome-dsh-plugin.com/p/ZhuYw3927/dsh-ai-collab

09 · 结语

它不发明新的工作流,只是让「交底、记账、校验」留在仓库里。

于是工具可以换、会话可以断、维护者可以更替,而项目的进度与判断依据不会丢。这就是 dsh-ai-collab 的全部野心:把一次性的会话成本,变成可继承的项目资产。

统一留存可持续