dsh-project-manager

给 DeepSeek Harness 加一块项目看板：卡片组管父项目，卡片管任务；每张卡片关联落盘项目记忆、挂载仓库、绑定会话，从卡片开的会话自动带上项目上下文。

English · Releases · 更新日志

安装

dsh plugin add dsh-project-manager

备选（直接从 GitHub 装）：

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

零配置、开箱即用：装完重启 dsh 即可，不需要账号、API Key 或任何设置项。落盘项目默认从 ~/.ai 只读扫描；要改数据目录或权限模式见下文「配置」。

适配的 dsh 版本

环境	版本	状态
dsh CLI（@deepseek-ai/dsh，dsh web）	0.2.0-rc.2	实测通过（0.11.0）
DSH Desktop	2.0.17（内置 dsh 0.2.0-rc.2）	实测通过（0.11.0）
dsh 0.1.5-rc.1	—	0.4.0 时实测通过；0.5.0 起未再验证
依赖范围（peerDependencies）	@deepseek-ai/cordis >=4.0.1 <5、@deepseek-ai/dsh-tools >=0.1.5-rc <2、@deepseek-ai/dsh-client-ui-slots >=0.1.5-rc <2、@deepseek-ai/schemastery ^3.18.1	声明范围，范围内其他版本未逐一验证

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

功能

看板

• 按项目看全局：每个卡片组一条泳道，阶段（列）名称、数量、顺序都能改；卡片在阶段内拖动排序（键盘 Alt+↑/↓），拖到别的阶段即推进。卡片组按住头部右侧的手柄拖动调整顺序；点头部左侧任意位置展开 / 收起。
• 每个阶段随手加卡：阶段底部常驻「添加卡片」，回车连续添加，Esc 收起；也能从落盘项目批量导入（一个 STATE 生成一张卡片并自动关联）。
• 卡片上只放两个小标志：会话标志（有活跃会话为绿色、全部已归档为灰色、没有会话不显示）和落盘项目数（有关联才显示）；子任务在详情里看。
• 卡片归档：卡片右上角或详情里点归档图标，或把卡片拖进展开的「已归档卡片」列表；「已归档卡片 N」默认收起，点开就地看列表，点一行看只读详情，「恢复活跃」回到原阶段。卡片的会话不动。
• agent 也能改看板：4 个工具 card_manage / repo_manage / phase_move / task_manage，在项目会话里不传 card 就作用于本会话的卡片。

卡片详情

• 本卡片的会话置顶：活跃的在前、已归档的在后，各自按更新时间新 → 旧；可直接打开、归档（与 dsh 侧栏「归档会话」同一动作，会话还在运行时先确认「停止并归档」，提示可撤销）、对已归档的「恢复活跃」回到工作区原位置；「解除关联」二次确认，不删会话。
• 关联已有会话：搜索会话名或仓库，活跃 / 已归档两列按仓库分组、新的在前，勾选后一次保存；一个会话只属于一张卡片。
• 落盘项目先看标题：「关联的落盘项目」默认每项只显示标题；一个「展开详情 / 收起详情」按钮一次展开或收起全部（项目名、更新日期、一行状态、next_action）。切换卡片时保持，重新打开看板回到收起。
• 相关说明 / 相关链接 / 相关文件：说明不限字数、网址可点、过长时折叠并给「展开全部 / 收起」；链接有显示文字、类型（默认「文档 / 代码」，可新增，全局共用）和完整网址，可批量添加、编辑、删除、拖动排序，点击用默认浏览器打开；文件用系统选文件对话框多选登记，显示存在 / 已删除，解除关联不删文件。
• 阶段与子任务：步骤条点一下就移到该阶段，或点「推进到 …」；子任务勾选、删除、回车添加。

侧栏「项目区」

• 项目区工作区：插件在工作区列表置顶一个「项目区」，每个卡片组是它的子工作区（dsh 视图选项选「按工作区树」时嵌套在「项目区」下），项目会话按卡片组归在这里。
• 活跃会话数：每个卡片组行右侧显示该组没归档的会话数，0 为灰色；新建、归档、恢复会话后即时更新，变化时轻跳一下。悬停时数字仍在，操作按钮出现在它右边。
• 层级一眼可见：卡片组下的会话整行缩进到一条竖向引导线右侧，选中底色、其他插件给会话行加的边框与填充都跟着缩进；展开的卡片组名加粗。
• 从看板进入会话自动展开：在详情里「打开」、在「新建会话」弹窗里打开、或以此卡片新建会话后，会话所在的卡片组（以及「项目区」）收起着就自动展开并滚到这个会话；已展开的不会被收起。
• 「+」先选卡片：点「项目区」或卡片组行的「+」，弹出选卡片浮层（卡片组行只列本组卡片，每行显示阶段、记忆数、会话数），再在「新建会话」弹窗里单选：新建一个会话，或打开这张卡片已关联的会话（已归档的可就地「恢复活跃」）。
• 「项目看板」主按钮：侧栏全局面板里与「插件」同一组，带「N 进行中」徽标，点一下打开看板。

会话

• 会话自动读记忆，读过的不重复：从卡片新建或手动关联的会话，每一轮自动注入「卡片组 ∪ 卡片」去重后的落盘项目记忆（一行状态、next_action、STATE 路径）；关联时扫描会话记录，已经 read 过的 STATE 不再注入。
• 卡片资料一起带上：卡片的相关说明（全文，超过 16KB 截断并注明）、相关链接（文字 + 网址 + 类型）、相关文件（绝对路径）作为「卡片资料」随记忆注入；没关联落盘项目时也照常注入。
• 记忆提示条：会话输入框上方显示「已自动读取 N 个落盘项目的记忆，M 个已读过不重复读取」，默认收起，展开看每项的 next_action。
• 同名落盘项目提示：卡片没关联任何落盘项目、但标题里含某个落盘项目名（如问题单号）时，「新建会话」弹窗和记忆提示条会给「关联」按钮，一键关联；不会静默自动关联。
• 项目会话默认完全权限，标题自动改为卡片名（「按工作区树」分组）或「卡片组 · 卡片」。

和已有插件的差别：看板类插件多数按工作区记待办；本插件不做通用待办，只做「项目 → 落盘记忆 → 仓库 → 会话」这条链：卡片即项目，会话自动继承项目上下文。

快速上手（30 秒）

1. 点击侧栏「插件」下面的「项目看板」主按钮，再点击右上角「新建卡片组」，输入组名后按回车。
2. 点击任意阶段底部的「添加卡片」，输入标题后按回车；可以连续输入多张。
3. 打开卡片详情，点击「关联的落盘项目」旁的「关联」，勾选落盘项目后保存。
4. 打开「卡片组设置」，点击仓库旁的「添加」，勾选 dsh 已有的工作区或点击「选择文件夹…」，再点击「保存」。
5. 点击卡片详情底部的「以此卡片新建会话」：会话出现在「项目区」下这个卡片组的子工作区，已带上记忆，侧栏卡片组行的数字加 1。

操作	结果
拖动卡片到别的阶段	卡片移到新阶段，events.jsonl 追加一条 move 记录
在阶段底部输入标题并回车	该阶段末尾出现新卡片，输入框保留可继续添加
以此卡片新建会话	会话出现在卡片组子工作区，卡片组行数字 +1，收起的组自动展开
在详情里归档一个活跃会话	卡片组行数字 -1，留在看板，提示可撤销
点「展开详情」	所有关联的落盘项目同时展开状态与 next_action
点击已归档会话的「恢复活跃」	会话回到工作区原来的位置，状态变成「活跃」
挂载一个已挂载过的路径	保存被拒绝，提示 REPO_MOUNTED 并点名已挂载的仓库

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

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

使用场景

• 一个需求跨多个仓库：卡片组挂上前端、SDK、基础设施几个仓库，项目会话里用 repos/<仓库>/ 统一读写，AGENTS.md 自动列出仓库清单。
• 长周期项目接续：/landfill-project 落盘的 STATE 关联到卡片，第二天从卡片开新会话，状态和 next_action 已经在上下文里，不用再「回忆」。
• 把零散会话收拢到项目：之前在各个工作区开的讨论会话，用「关联已有会话」挂到同一张卡片下，项目进展一眼看全。
• 每天开工先看全局：侧栏每个卡片组的活跃会话数、看板上每张卡片的阶段和会话标志，打开就知道哪些项目在推进。
• 找回归档过的会话：之前归档的讨论又要继续时，在卡片里一键「恢复活跃」，会话回到原工作区原位置继续用。
• 交接给同事或新会话：卡片上的落盘项目、相关说明、链接、文件和会话列表就是交接清单，新会话从卡片打开即可接手。
• 按阶段做评审：卡片组的阶段可以按团队流程命名（如「方案 → 开发 → 验收」），评审时按列逐张过卡片。
• 让 agent 自己推进：在项目会话里让 agent 调 phase_move 推进阶段、task_manage 勾子任务，看板实时更新，每次移动写审计日志。

运行效果

• 侧栏「项目区」下每个卡片组行带活跃会话数，会话整行缩进在引导线右侧，从看板进入的会话所在组自动展开。
• 看板卡片显示会话标志与落盘项目数；详情里落盘项目默认只显示标题，一键全部展开。
• 会话输入框上方出现记忆提示条，展开看每项的 next_action；卡片资料随记忆注入。
• 「项目区」及卡片组子工作区里的会话默认完全访问权限，标题自动改为卡片名或「卡片组 · 卡片」。
• 项目区目录生成 repos/<卡片组>/<仓库> 软链接和 AGENTS.md，每个卡片组子目录有本组的 repos/<仓库> 和 AGENTS.md，仓库里的 AGENTS.md / CLAUDE.md 按字面路径加载。
• 每次移动、关联、挂载都追加到 events.jsonl，可追溯谁（用户 / agent）在什么时候做了什么。
• 深色主题跟随 dsh，看板右上角可一键切换。

配置

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

- id: dsh-project-manager
  config:
    dataDir: ''                              # 缺省 <DSH_HOME>/dsh-project-manager
    aiRoot: ''                               # 缺省 ~/.ai（只读）
    hubTitle: 项目区
    projectSessionMode: danger-full-access   # 或 inherit（跟随全局权限）
    memoryMaxBytes: 6000                     # 每个会话注入的项目记忆上限，1000–32000

工作原理

• 数据：看板存在 <dataDir>/board.json（原子写 + 串行变更），审计追加到 events.jsonl；落盘项目按需只读扫描 ~/.ai/projects/*/memory/designs/*/STATE.md。
• 项目区：插件用官方 workspaceRegistry 登记一个工作区（目录 <dataDir>/hub）并保持置顶；每个卡片组再登记一个子工作区（hub/groups/<组 id>，标题 = 组名），dsh「按工作区树」分组按目录嵌套显示。仓库以软链接挂在 hub/repos/<组>/<仓> 与 hub/groups/<组 id>/repos/<仓> 下。
• 记忆注入：通过官方 systemPrompt.context 按会话注入卡片记忆与卡片资料；文本不变不重发，关联时算出的「已读」集合固定不变，避免反复注入。
• 会话与归档：候选来自 dsh 的会话列表与工作区列表；归档调用 workspaces.archiveSession，恢复调用 workspaceRegistry.unarchiveSession（dsh-manage-sessions 提供）；归档不改变会话在工作区里的顺序，所以恢复即回原位。
• 界面：看板是主区面板；「项目看板」主按钮走官方全局面板入口 sidebar.panellist。侧栏的活跃会话数与层级是一张按行 id 生成的样式表（[data-row-key="workspace:<id>"]），不改 dsh 的页面节点；「+」接管与自动展开是 DOM 增强（自动展开 = 对收起的行模拟一次点击）。找不到这些行时安静跳过，官方「+」照常新建会话。

可靠性与验收

• 隔离验证：每个版本先在独立的 staging DSH_HOME 装配，冷启动静态检测（依赖链接 / bundle 清单 / 运行时导入 / 重复 entry 等六类）本插件项全绿后才装到主实例。
• 真实 GUI 测试：Playwright 在真实 dsh web 上跑完整交互，0.11.0 新增 22 项（数字 1→2→1→2、灰色 0、其他工作区无数字、会话行整行缩进与引导线位置、收起卡片组 / 项目区后从看板进入自动展开、已展开不误收、落盘项目默认只显示标题与一键全开全收），旧版回归 28 + 36 + 42 + 8 项，全部通过、0 页面报错。
• 主实例验收：每个版本装到日常使用的 dsh 后，用只读探针确认新逻辑已生效（0.11.0：卡片组数字、两种分组下的缩进、dsh-kiro 会话样式跟着缩进、从看板打开后自动展开）。
• 卸载重装幂等：卸载后无样式、无入口、无侧栏数字、路由 404、用户数据保留；重装后数据与关联完整恢复，再跑一遍全部通过。
• 升级验证：用上一版构建灌旧数据，原地升级后读取无损（旧数据缺少的字段按默认值处理，无需迁移）。
• 单元测试：49 项 node:test 覆盖看板模型、批量挂载冲突、会话批量关联与移动、已读判定、记忆预算与省略提示、卡片资料注入、链接校验、软链不越界。
• 失败会点名：冲突与错误返回明确代码与对象，如 REPO_NAME_TAKEN、REPO_MOUNTED、BAD_URL（点名第几条）、CARD_ARCHIVED、UNARCHIVE_UNAVAILABLE，不静默吞掉。
• 兼容与限制：「恢复活跃」依赖 dsh-manage-sessions 的核心补丁，缺失时按钮置灰并说明原因；多个 dsh 进程共用同一 DSH_HOME 时没有跨进程锁。
• 安全边界：项目会话默认完全访问（只对项目区目录的会话生效，可改 inherit）；HTTP 路由只接受本机回环、写操作校验同源，没有登录态校验；不读写凭据、不访问网络、不执行 git；删除卡片组只删软链接，不删真实仓库。

常见问题

• 侧栏没看到「项目区」？ 新建第一个项目会话后才会登记；在那之前用侧栏「项目看板」主按钮。
• 卡片组没有嵌套在「项目区」下？ 在工作区列表标题旁的「视图选项」里把分组方式选成「按工作区树」。
• 卡片组行没有数字 / 会话没有缩进？ 只有「项目区」下的卡片组子工作区才显示；dsh 改版导致页面结构变化时这两项会自动不显示，请提 issue 并附 dsh 版本。
• 从看板打开会话后，卡片组没展开？ 只对「项目区」及卡片组里的会话生效；侧栏收成图标栏时没有可展开的行。
• 「恢复活跃」是灰的？ 当前 dsh 没有 workspaceRegistry.unarchiveSession，装 dsh-manage-sessions 并应用它的核心补丁即可。
• 「选择文件夹…」变成了输入框？ dsh 使用网页文件浏览器（非本机访问或远程）时打不开系统对话框，直接输入绝对路径。
• 新会话侧栏显示「新会话」？ 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、hub/），需要时手动删除。

本地构建

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

许可证

MIT