dsh-project-manager

dsh-project-manager

给 DeepSeek Harness 加一块项目看板，并把「项目记忆」做成插件的本职：从卡片打开的会话，自动带上这个项目完整、最新的落盘记忆（STATE + 必读子文档）和卡片资料；说一句「落盘项目」就把进展按规范写回去，换会话、换 CLI、隔几天都能接着做。

English · Releases · 更新日志

安装

dsh plugin add dsh-project-manager

备选（直接从 GitHub 装）：

dsh plugin add github:hoyyang/dsh-project-manager

零配置、开箱即用：装完重启 dsh 即可，不需要账号、API Key 或任何设置项。落盘项目默认读写 ~/.ai（写入一律经插件自带的 ai-memory，需要 python3；Windows 上这块自动关闭，看板照常）。要改数据目录或权限模式见下文「配置」。

需要 dsh web 界面（CLI 的 dsh web 或 DSH Desktop）。侧栏增强（项目区数字、层级、「+」接管、空会话行）依赖 dsh 工作区列表的页面结构；dsh 改版后若对不上，这几项会自动不显示，看板、会话与落盘功能不受影响。

功能

会话自动带上完整、最新的项目记忆

• 从卡片开会话 = 上下文已经在了：卡片关联的落盘项目（STATE + 标 [必读] 的子文档）由插件把全文直接放进会话，系统提示里另有一段实时生成的「卡片档案」（仓库、子任务、说明、链接、文件）。不用先说「回忆」，第一句就能接着干。
• 永远是最新版，且不重复：别的会话或 Codex / Claude Code 等其他 CLI 改了 STATE，下一步自动补上新版（标明替代哪一版、谁写的）；会话压缩后重新补齐；同一版本只放一次，自己写的不回灌，分叉会话继承。
• 看得见 AI 收到了什么：会话信息卡里「查看 AI 收到的原文」逐字显示系统提示和注入的全文，标出版本、是否已在本会话、约多少 token，可一键复制。

说一句「落盘项目」，按规范写回去

• 一句话触发：会话里说「落盘项目 XX」把进展写进 XX 的 STATE，说「回忆 XX」/「继续 XX」先读全再接着做；触发词来自 ~/.ai 里现有的项目名和别名。只认指令写法，讨论「落盘项目这个功能」时不会误触发；规划模式下只提示不拉回。
• 防丢事实：没读全不能写；新稿少了旧稿里的 commit、路径、版本号、单号又没声明删除，直接拒绝；写完回读校验并给出前后大小、删掉了哪些章节。用户要求了而这一轮没做到，回合结束前把模型拉回补做。
• 一个项目一个文件夹：STATE.md 是唯一入口，plans/（批准的计划自动存进来）notes/ evidence/ 里每个文件都要在「📁 文件索引」里有一行；每次落盘都整体重写 STATE、顺手整理文件夹（重复的合并、过时的退役到回收区）。
• 卡片档案进 STATE：插件按看板生成「🗂 卡片档案」块写进 STATE（AI 不写），其他工具读 STATE 也能看到卡片资料。
• 防绕过：write / edit / bash 直接改 ~/.ai 下的记忆文件会被拒绝；写入只经 ai-memory（文件锁 + 乐观并发），和其他 CLI 共用同一个 ~/.ai 也不会互相覆盖。

会话信息卡：这个会话属于哪张卡片、带着什么，一眼看清

• 输入框上方一行：卡片组 / 卡片、落盘项目数、仓库 / 链接 / 子任务 / 说明胶囊，一键直达看板上的这张卡片。有关联是浅蓝，没关联是浅灰。
• 展开看全部：每个落盘项目一行（所属项目、别名、next_action、是否已注入、字数），可以单独「落盘」；下面是卡片资料。
• 落盘的结局如实显示：从信息卡点了落盘之后，这一轮写好了提示「落盘完成」；被你停止、出错、或者 AI 在问你，都会写明，并给「重新落盘 / 忽略」，不会一直转圈。

同名检测：不让同一个项目被建成两份

• 还没输入就提示：卡片没关联落盘项目时，按卡片名找到别名相同的已有项目，提示「可能就是这个」。
• 完全同名不让新建：输入的文件名或别名和已有项目相同，主按钮换成「关联并落盘」，并给出改名建议；名字相近时只提示，确认不是同一个可以照常新建。
• 每个候选看得清：字数、更新时间、已经关联了哪些卡片、落盘时会不会迁移；可以「只关联」，也可以「关联并落盘」。

按卡片组归档，按规范自动迁移

• 每个卡片组有自己的落盘文件夹：~/.ai/projects/<文件夹>/。第一次在这个组落盘时，信息卡请你确认一次（按组名给建议，可改），卡片组设置里也能改。新建、合并的落盘项目都放进这里。
• 规范是一张带版本号的检查清单：每次落盘都整张检查，所以不管 STATE 是按哪个旧版本写的，下次落盘都会被拉到最新规范。位置不对的由插件把整个文件夹迁过来（子文档一起搬、里面的旧路径改指新位置、~/.ai 里的外部引用改指向、卡片关联换成新位置，旧文件夹进回收区）；标题行、文件索引、别名行由落盘的 AI 按清单改好，不合规范不让写。
• 提前告诉你，事后能撤销：信息卡上提前标出「落盘时迁到 xxx」；迁移后显示「已按规范迁移」卡片，可以撤销（搬回原处，之后不再自动迁）或删除旧文件夹。跨组共用的留在第一个关联它的组；旧项目不会被主动批量迁移，只在被落盘时迁。

合并落盘项目

• 几份合成一份：同一张卡片关联的几个落盘项目可以合并（勾选要合的，没选的不动）。AI 读全每一份、先写要点再整体重写成一份 STATE；插件校验来源里的关键事实都还在，再按规范把所有文件放进合并结果文件夹（重复的只留一份，~/.ai 外引用的文件复制进 evidence/）。
• 旧名字变成别名：说「回忆 + 旧名字」照样能找到；卡片关联和 ~/.ai 里指向旧路径的引用一并改好。
• 可撤销、可删除、可嵌套：合并前的文件夹进回收区，可以撤销（只退一步），也可以永久删除；合并结果还能再合并。

看板：卡片组管父项目，卡片管任务

• 按项目看全局：每个卡片组一条泳道，阶段（列）名称、数量、顺序都能改；卡片在阶段内拖动排序（键盘 Alt+↑/↓），拖到别的阶段即推进；卡片组可拖动排序、点头部展开 / 收起。
• 卡片组标题旁的统计：卡片数是蓝底胶囊（0 张变灰），旁边「● N 活跃会话」= 本组卡片关联、没归档的会话数，会话一开一归档就更新；仓库数和阶段数是灰色小字。
• 每个阶段随手加卡：阶段底部常驻「添加卡片」，回车连续添加；也能从落盘项目批量导入（一个 STATE 生成一张卡片并自动关联）。
• 卡片上只放两个小标志：会话标志（有活跃会话为绿色、全部已归档为灰色）和落盘项目数。
• 卡片归档：点归档图标或拖进「已归档卡片」列表；归档的卡片可看只读详情、「恢复活跃」回原阶段。
• agent 也能改看板：card_manage / repo_manage / phase_move / task_manage 四个工具，在项目会话里不传 card 就作用于本会话的卡片。
• 深色主题：跟随 dsh，看板右上角可一键切换。

卡片详情

• 以此卡片新建会话：点了立刻显示「正在新建会话…」并锁住按钮，侧栏同时出现占位行；建好后侧栏那一行就是「卡片名 · 未开始」。会话默认完全权限，标题自动改成卡片名或「卡片组 · 卡片」。
• 本卡片的会话置顶：活跃在前、已归档在后，各自按更新时间排序；可打开、归档（还在运行时先确认「停止并归档」，可撤销）、「恢复活跃」回原位置、解除关联；还没对话的会话可以删除（需要 dsh-manage-sessions）。
• 关联已有会话：搜索会话名或仓库，活跃 / 已归档两列按仓库分组，勾选后一次保存；一个会话只属于一张卡片，分叉出来的会话自动跟着源会话的卡片。
• 关联的落盘项目：默认只显示标题，「展开详情」一次展开全部（项目、更新日期、一行状态、next_action）；下面「回忆」「落盘」两个按钮发到这张卡片最近的会话。
• 相关说明 / 相关链接 / 相关文件：说明不限字数、网址可点、过长折叠；链接有显示文字、类型（全局共用，可在「管理类型」里新增、改名、拖动排序）和完整网址，可批量添加，编辑 / 删除按钮常驻显示，可拖动排序、复制；文件用系统对话框多选或「粘贴路径」一次贴多行（逐行检查存在 / 是文件夹 / 不存在 / 已关联）。
• 阶段与子任务：步骤条点一下就移到该阶段；子任务勾选、删除、回车添加。

仓库

• 卡片共用仓库 + 卡片自己的仓库：卡片组设置里的仓库是「卡片共用」，新建卡片时自动带上；卡片还可以加自己的仓库。候选来自 dsh 已有工作区和任意卡片组 / 卡片添加过的仓库，也可以「选择文件夹…」。
• 项目会话统一路径：仓库以软链接挂在会话目录的 repos/<仓库>/ 下，并生成 AGENTS.md 列出仓库清单；从这个路径读写，仓库自己的 AGENTS.md / CLAUDE.md 才会加载。同名不同路径的自动改成「名-2」。

侧栏「项目区」

• 项目区工作区：插件在工作区列表置顶一个「项目区」，每个卡片组是它的子工作区（视图选「按工作区树」时嵌套显示），项目会话按卡片组归在这里。
• 活跃会话数 + 层级：每个卡片组行显示没归档的会话数（0 为灰色，变化时轻跳）；组下会话整行缩进到引导线右侧。
• 还没对话的会话也显示：dsh 默认隐藏空会话，插件把它们补画成「卡片名 · 未开始」行，当前打开的也一样，可直接删除。
• 从看板进入自动展开：从详情打开或新建会话后，所在卡片组收起着就自动展开并滚到这个会话。
• 「+」先选卡片：点「项目区」或卡片组行的「+」，先选卡片（只列本组卡片，带阶段、记忆数、会话数），再新建会话或打开它已关联的会话。
• 「项目看板」主按钮：与「插件」同一组，带「N 进行中」徽标（没归档、且至少有一个没归档会话的卡片数）。

和已有插件的差别：看板类插件多数按工作区记待办；本插件不做通用待办，只做「项目 → 落盘记忆 → 仓库 → 会话」这条链，而且把记忆的读、写、规范、迁移、合并都做进插件里：卡片即项目，会话自动继承完整、最新的项目上下文。

快速上手（30 秒）

1. 点击侧栏「插件」下面的「项目看板」，再点右上角「新建卡片组」，输入组名后回车。
2. 点击任意阶段底部的「添加卡片」，输入标题后回车。
3. 打开「卡片组设置」，在「卡片共用仓库」里添加仓库；需要的话把「落盘文件夹」也设好。
4. 在卡片详情点「以此卡片新建会话」：会话出现在「项目区」下这个卡片组里，已带上卡片资料。
5. 在会话里干完一段，说「落盘项目」（或点信息卡上的「新建并落盘」），进展就写进这张卡片的落盘项目；下次从卡片开会话，记忆自动就在。

在项目会话里让 agent 操作看板（不传 card 就作用于本会话的卡片）：

> 把这张卡片推进到「验收」，再加一个子任务「补回归用例」
phase_move  { "status": "verify" }                     → {"ok":true,"event":{"kind":"move","from":"开发","to":"验收"}}
task_manage { "op": "add", "text": "补回归用例" }      → {"ok":true,"tasks":[…,{"text":"补回归用例","done":false}]}

读写落盘项目（插件注册的 landfill 工具，模型按 skill 协议调用）：

landfill { "op": "recall" }                          → 分段读 STATE + [必读]，读到 complete:true
landfill { "op": "persist", "content": "…", "drop": ["a1b2c3d"] } → {"key":"checkout/checkout-flow","verified":true,"migrated":{…}}

使用场景

• 长周期项目接续：今天落盘，明天从卡片开新会话，状态、决策、next_action 已经在上下文里，不用重新交代。
• 多个 CLI 共用一份记忆：DSH 里落盘，Codex / Claude Code 读同一个 ~/.ai 的 STATE；它们写了，DSH 这边下一步自动拿到新版。
• 一个需求跨多个仓库：卡片组挂上前端、SDK、基础设施几个仓库，项目会话里用 repos/<仓库>/ 统一读写。
• 收拾散落的记忆：同一件事以前落成了好几份，用「合并」合成一份，旧名字当别名；放错地方的，下次落盘自动迁到卡片组的文件夹。
• 把零散会话收拢到项目：之前在各处开的讨论会话，用「关联已有会话」挂到同一张卡片下。
• 每天开工先看全局：卡片组标题旁的卡片数和活跃会话数、卡片上的会话标志，打开看板就知道哪些项目在推进。
• 交接给同事或新会话：卡片的落盘项目、说明、链接、文件和会话列表就是交接清单。
• 让 agent 自己推进：在项目会话里让 agent 推进阶段、勾子任务，看板实时更新，每次变更写审计日志。
• 一单一卡处理问题单：卡片标题写问题单号，落盘项目以单号为别名；下次在任意会话说「回忆 + 单号」就能找回分析进度。
• 规范升级不用手工迁移：老版本写的 STATE 不用一次性整理，哪个项目再被落盘，哪个就自动迁到卡片组的文件夹并补齐规范项。

运行效果

• 从卡片开的会话第一步就带着 STATE 与 [必读] 全文，系统提示里只有一段「项目记忆」（卡片档案 + 落盘项目索引）。
• 落盘后 STATE 位于 ~/.ai/projects/<卡片组的落盘文件夹>/memory/designs/<名字>/STATE.md，带卡片档案块、文件索引、别名行。
• 会话信息卡实时显示落盘这一轮的结局；同名检测边输入边给出候选。
• 侧栏「项目区」下每个卡片组行带活跃会话数，会话整行缩进；新建的空会话直接显示卡片名。
• 每次移动、关联、挂载、迁移都追加到 events.jsonl，可追溯谁（用户 / agent）在什么时候做了什么。
• 合并完成后，合并结果文件夹里是 STATE.md、notes/（每份来源的要点）和 evidence/，合并前的文件夹在各自项目的 inbox/retired/ 下。
• 迁移完成后，旧文件夹在原项目的 inbox/retired/<时间>-migrate-<名字>/ 下，信息卡显示子文档数和改了几处外部引用。
• 「查看 AI 收到的原文」显示系统提示字数、注入全文份数与总字数、约多少 token。

配置

零配置即可使用。需要时在 profile 的 cordis.patch.yml 加顶层 id 条目覆盖（不要放进 insert: 列表）：

- id: dsh-project-manager
  config:
    dataDir: ''                              # 缺省 <DSH_HOME>/dsh-project-manager
    aiRoot: ''                               # 缺省 ~/.ai
    landfill: true                           # 落盘项目工具 / 识别 / 拦截 / 收尾检查（false = 只读扫描）
    agentsHome: ''                           # landfill-project skill 链接所在的 ~/.agents
    hubTitle: 项目区
    projectSessionMode: danger-full-access   # 或 inherit（跟随全局权限）
    memoryMaxBytes: 6000                     # 系统提示里项目记忆段的上限，1000–32000

卡片组的落盘文件夹在「卡片组设置」里改，不需要写配置。

工作原理

• 数据：看板存在 <dataDir>/board.json（原子写 + 串行变更），审计追加到 events.jsonl；落盘项目按需扫描 ~/.ai/projects/*/memory/designs/*/STATE.md；写入只经 ~/.ai/tools/ai-memory（Python 标准库：fcntl 文件锁 + expected-hash + journal）。合并与迁移记录在 <dataDir>/merges.json / migrations.json。
• 注入：系统提示一段（卡片档案每步按看板现生成 + 落盘项目索引）；STATE 与 [必读] 全文在 agent/pre-step 作为一次性消息注入，按「会话 × 文件版本」记已知，跨重启保存；看到压缩事件就重注。
• 落盘触发：agent/pre-step 识别用户原话并追加提示；tools/pre-execute 拦截直写；agent/turn-stopping 收尾检查并拉回；会话事件 turn/end 的结束原因（完成 / 停止 / 出错）驱动信息卡上的落盘状态。
• 规范与迁移：规范清单（v2：位置、标题行、文件索引、别名行含卡片名）在每次 persist 前检查；位置项由插件用 ai-memory retire-dir / write / import / update-state 整体搬迁，中途失败按已做的倒着撤回。
• 项目区：用官方 workspaceRegistry 登记「项目区」工作区（<dataDir>/hub）与每个卡片组的子工作区，仓库以软链接挂在 repos/<仓> 下。
• 界面：看板是主区面板；「项目看板」主按钮走官方 sidebar.panellist；会话信息卡走 conversation.input.dock；侧栏数字与层级是一张按行 id 生成的样式表，「+」接管、空会话行、自动展开是 DOM 增强，找不到对应行时安静跳过。

可靠性与验收

• 隔离验证：每个版本先在独立的 staging DSH_HOME 装配，冷启动静态检测（依赖链接 / bundle 清单 / 运行时导入 / 重复 entry 等六类）本插件项全绿后才装到主实例。
• 真实模型端到端：0.20 在 staging 用真实模型跑「落盘 → 自动迁移 → 规范检查 → 迁移卡 → 撤销」与「新建落盘进卡片组文件夹」；0.19 用 6 份真实落盘项目副本跑合并、嵌套合并、子删除、撤销逐字节还原。
• 真实 GUI 测试：Playwright 在真实 dsh web 上逐项点：组头统计、新建会话忙态与侧栏标题、链接按钮常驻、箭头方向、同名三种情况、卡片组落盘文件夹确认与非法名字提示、停止后状态与忽略、整页不移位，全部通过、0 页面报错。
• 主实例验收：每个版本装到日常使用的 dsh 后，用探针确认新逻辑已生效（0.20：组头统计、新建会话忙态与侧栏「卡片名 · 未开始」、链接按钮、箭头、同名检测）。
• 单元测试：96 项 node:test（看板模型、注入与已读判定、落盘防丢、合并全链路、规范清单、同名匹配、迁移与撤销、落盘状态跟踪）+ 9 项 ai-memory 测试。
• 失败会点名：NEED_FULL_READ、DROPPED_ANCHORS、UNINDEXED_FILES、SPEC_ISSUES、NEED_GROUP_FOLDER、MIGRATE_CLASH、FOLDER_TAKEN、REPO_MOUNTED 等错误码点名对象，不静默吞掉。
• 兼容与限制：「恢复活跃」和删除空会话依赖 dsh-manage-sessions，缺失时按钮置灰或不显示；落盘项目需要 python3（Windows 关闭）；多个 dsh 进程共用同一 DSH_HOME 时看板没有跨进程锁（~/.ai 写入有）。
• 安全边界：项目会话默认完全访问（只对项目区目录的会话生效，可改 inherit）；HTTP 路由只接受本机回环（Host 必须是 127.0.0.1 / localhost），写操作带 Origin 时必须同源（DSH Desktop 壳转发会去掉 Origin，此时放行），没有登录态校验；插件会写 ~/.ai、建 ~/.agents/skills/landfill-project 链接；不读写凭据、不访问网络、不执行 git；删除卡片组只删软链接，不删真实仓库。

常见问题

• 侧栏没看到「项目区」？ 新建第一个项目会话后才会登记；在那之前用侧栏「项目看板」主按钮。
• 卡片组没有嵌套在「项目区」下？ 在工作区列表标题旁的「视图选项」里把分组方式选成「按工作区树」。
• 第一次落盘为什么问我落盘文件夹？ 新建和迁移的落盘项目要放进卡片组自己的文件夹，只问一次；以后在卡片组设置里改。
• 我的旧落盘项目会被搬走吗？ 只有在你对它落盘、且它关联的卡片组设了落盘文件夹时才迁；迁移后可在信息卡撤销，撤销后不再自动迁。
• 落盘被拒了怎么办？ 看返回的错误码：没读全就先回忆；少了关键事实就补回或写进 drop；SPEC_ISSUES 按列出的规范项改。
• 「恢复活跃」是灰的？ 当前 dsh 没有 workspaceRegistry.unarchiveSession，装 dsh-manage-sessions 并应用它的核心补丁即可。
• 「选择文件夹…」变成了输入框？ dsh 使用网页文件浏览器（非本机访问或远程）时打不开系统对话框，直接输入绝对路径。

卸载

1. 调用 POST /_dsh/dsh-project-manager/api/hub/cleanup（或在工作区列表手动移除「项目区」和各卡片组工作区），撤销插件登记的工作区条目；会话与文件不会被删除。
2. dsh plugin --profile web remove dsh-project-manager，重启 dsh。
3. 数据保留在 <DSH_HOME>/dsh-project-manager/（board.json、events.jsonl、merges.json、migrations.json、hub/、backups/），需要时手动删除。
4. 落盘项目：~/.ai（含插件补建的 tools/ai-memory）是共享记忆，卸载不删。~/.agents/skills/landfill-project/SKILL.md 若是指向插件的链接，卸载后会断开；要留 skill 就把 backups/ 里的备份（或插件包里的 SKILL.md）复制回去。

本地构建

npm install
npm run build          # host：tsc → lib/
npm run build:client   # client：tsdown → lib/client.js
npm run typecheck
npm test               # node:test 单测 + ai-memory 测试

许可证

MIT