重复交底
构建、烧录、编码约定散落在聊天窗口与个人笔记里,换一个工具就要重讲一遍。
DeepSeek Harness Bundle · 项目无关的 AI 协作层
dsh-ai-collab 在仓库里放下两样东西:一个所有工具共用的 AGENTS.md,和一个只追加、可校验的 .ai/ 工作记录层。
项目事实、当前进度、历史决策,从此只有一份。
$ .ai\llm.cmd status project sample-firmware phase maintain focus uart-dma blockers — last fix · ok · 2026-11-20T09:39+08:00 "修正 DMA 环形缓冲边界,rebuild 0/0" $ .ai\llm.cmd tail -N 2 ● 11-20 09:39 fix 修正 DMA 环形缓冲边界 ● 11-19 18:02 build rebuild 0/0,Code=124476 $
01 · 问题
多 AI 工具协作时,最贵的成本往往不是写代码,而是让每个新会话重新理解项目——构建命令、烧录地址、只读目录、上次改到哪、为什么这样改。
构建、烧录、编码约定散落在聊天窗口与个人笔记里,换一个工具就要重讲一遍。
上一个会话的结论只活在上下文里;窗口一关,项目就回到「未读」状态。
DSH、Claude Code、Cursor、Copilot 各记各的,没有一份共同的事实源。
改了什么、怎么验证、下一步是什么,只剩人的记忆和零散的提交说明。
最贵的不是写代码,而是让每个新会话重新理解项目。交底、记账、校验本来就要做——插件只是把它们变成仓库里的文件,而不是会话里的消耗品。
02 · 机制
它不改变工程结构,只在项目根增加两样东西。AGENTS.md 负责「说清楚」,.ai/ 负责「记下来」。
唯一入口
所有工具开工先读:项目事实(构建、烧录、只读目录、编码约定)与固定动作(开工读什么、收工写什么)。纯文本、可 diff、可评审。
协作层
追加式日志、当前状态快照、版本级变更、schema 与归档。所有写入经由 .ai\llm.cmd 或 5 个原生工具,编码与格式由脚本保证。
与语言、框架、IDE 无关:嵌入式固件、桌面应用、脚本仓库、文档工程共用同一套协议。
03 · 统一进度
工具可以换,入口不变。每个工具开工前读同一份快照,收工后写同一条流水;人也不例外。
| 工具 | 接入方式 | 参与方式 |
|---|---|---|
| DSH | Bundle 安装,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.cmd | status / tail / add / check |
| 人 | 同一条命令 | tool: human,决策与验收也入账 |
status 与 tail -N 10:当前阶段、焦点、阻塞、下一步,以及最近十条记录。
add 自动生成 id 与时间戳,刷新 status.json,并在需要时刷新看板与 TASKS.md。
check 检查必填字段、枚举、时区、时间单调与 id 唯一,可选扫描敏感信息。
换工具不换进度,换会话不换上下文。
04 · 本地记录
聊天记录会消失,仓库里的文件不会。每次工作被压成一行可校验的 JSON,「当前状态」与「版本级细节」分开存放。
UTF-8 无 BOM、LF、一行一个 JSON 对象。写错就追加一条 correction,用 corrects 指向原记录;历史行永不修改或删除。
phase、focus、blockers、next、last_log。新工具先读这一份,不必翻完整本流水。
根因、实测数据、补丁与已知限制。日志里的 summary 用 refs 指过去,不把单条记录撑大。
必填字段、枚举、时区、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"]
}
目标只有一个:任何时候都能回答——谁做的、改了什么、怎么验的、下一步是什么。
工作记录不出工作区。插件不发起网络请求、不写注册表、不接触凭据;敏感值放 .ai/private/,文档只写键名。任务清单在插件进程内渲染,克隆来路不明的仓库并记录日志,也不会执行仓库里的脚本。
05 · 分区设置
AGENTS.md 被两条标记切成两个区。插件升级时只重写 generated 区,项目事实与区外内容逐字节保留。
开工 / 收工固定动作、目录与权限表、构建与验证、硬性约束、领域文档索引、多工具入口。
<!-- dsh-ai-collab:generated:end --> <!-- dsh-ai-collab:user:start -->
项目名、根目录、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 会在每个会话注入它——不依赖模型记性,也不依赖项目是否已经接入。它是可加载的:改一次文件,之后每个会话都带着同一套纪律开始。
全局文件只放跨项目纪律,没有任何项目事实。项目事实留在 <项目根>/AGENTS.md。编辑全局文件对下一次请求立即生效,无需重启;插件代码升级才需要重启 DSH。
每个会话先保证接入与同步:缺骨架则生成、模板过期则升级、看板过期则刷新。临时或系统目录返回 not-project,不强行接入。
动手前给出本轮目标、待定项、方案与取舍;确认后执行。纯只读查询例外。
详细记录只留在各自项目的 .ai/;跨项目看板只读汇总,禁止反写项目内容。
工程文件默认只读;写未列出的路径,先说明原因与影响范围,确认后更新权限表再动手。
status + tail 开工,add 收工,check 校验。没写记录 = 这件事没做完。
generated 区归模板,user 区归项目;重渲染只替换 generated,事实逐字节保留。
临时目录、只读目录、工作区之外不接入;凭据、内网地址、客户信息不进日志。
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 · 快速开始
安装一次,之后每个会话只重复三个动作:读状态、干活、写记录。
推荐。选择本包绝对目录即可。
plugin_manager
action: install_bundle
target: <包绝对路径>
npm 包名或本地目录均可。
dsh plugin --profile <profile> add dsh-ai-collab
# 或本地目录
dsh plugin --profile <profile> add "<包绝对路径>"
仅开发调试;生产安装走 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
| 命令 | 作用 | 何时用 |
|---|---|---|
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 | 环境与文件自检 | 接入异常时 |
| 配置 | 默认 | 含义 |
|---|---|---|
autoInit | false | 会话创建时对工作区跑 ai-ensure(排除临时 / 系统目录) |
maxTail | 10 | ai_status 返回的最近记录条数 |
initScript | 包内 ai-ensure.ps1 | 覆盖接入脚本(调试用) |
08 · 边界与状态
0.4.4 已上 npm 并被社区插件市场收录;脚手架目前仅支持 Windows,只读工具与任务渲染本身与平台无关。
| 兼容性 | 要求 |
|---|---|
| DSH | 0.2.1+(在 0.2.2-rc.3 上实测) |
| Node.js | >= 20;DSH 内置 Electron Node 可用 |
| 操作系统 | Windows 10 / 11;包声明 "os": ["win32"] |
| 网络 / 凭据 | 都不需要;数据只写工作区与本地日志目录 |
| 许可证 | MIT;另附 免责声明 与 建议性非商业声明(不改变 MIT 权利) |
unsupported-platform;只读工具与任务渲染本身不依赖平台。ai-collab-config.log,不会静默沿用。-ForceAgents 或 -ResetAgents。.ai\board.md 时生成跨项目看板。AGENTS.md 编辑对下一次请求立即生效。下一步:跨平台 Node 脚手架 · 导出 Config schema。市场详情页:awesome-dsh-plugin.com/p/ZhuYw3927/dsh-ai-collab
09 · 结语
于是工具可以换、会话可以断、维护者可以更替,而项目的进度与判断依据不会丢。这就是 dsh-ai-collab 的全部野心:把一次性的会话成本,变成可继承的项目资产。