项目工作区 lord-of-vaegirs/dsh-projectflow

dsh-projectflow

以项目为中心的 DeepSeek Harness 工作区。 这是一个 DSH 插件，让项目——而不是当前文件夹——成为上下文、任务状态、引用和工作区组合的持久单位。

dsh-projectflow 给每个项目一个稳定 id，并在 $DSH_HOME/projects/<projectId>/ 下给一个数据归宿。任何目录里的任何会话都能加入同一个项目，继承它的约定、决策、进度、引用和当前任务检查点。项目数据在插件卸载、DSH 重启、工作目录变更之后依然存在。

- 以项目为中心的上下文 —— 每轮都把一段有边界的项目摘要注入系统提示词。
- 任务结构 —— 像操作系统进程记录一样给当前任务做检查点；查看 last/next/blocked 和待处理的工具。
- 引用而不复制 —— 把目录、文件、工具、插件、MCP 服务器记录为元数据；绝不把内容复制进项目。
- 工作区组合 —— 插入其他会话、目录或项目；分叉项目；合并项目并保留或丢弃源项目；删除到回收站。
- 两个界面 —— TUI/无头模式用 /project 命令，项目工作区用浏览器/Desktop 面板。
- 本地优先 —— 不发网络请求，不依赖外部服务。所有数据都是可读的 Markdown/JSON。

状态：0.1.0，已针对 DSH CLI 0.2.1-rc.2 测试。随附的 Desktop 应用 0.2.0-rc.2 无法从命令行安装，不声称已测试。见兼容性。

目录

- 为什么
- 安装
- 快速开始
- 命令界面
- 工具界面
- 项目工作区
- 数据模型
- 架构
- 任务调度语义
- 浏览器 / Desktop 面板
- 容量、原子性、并发
- 安全与隐私
- 兼容性
- 开发
- 测试
- 已知限制与路线图
- 许可证

为什么

DSH 把会话绑定到一个工作目录。真实工作常常横跨多个目录：一个服务、一个库、一个运维文件夹、第二份检出、一个设计目录，还有一组根本不是文件的工具。在每个会话里记住项目规则很脆弱，把上下文复制进每个新文件夹又会让真相分叉。

dsh-projectflow 补上缺失的那一层：

- 项目是一等实体，有稳定的 id；
- 它的记忆独立于当前文件夹；
- 会话可以显式加入，fork 会继承；
- 任务状态写下来，而不是从聊天记录里猜；
- 引用只描述东西在哪，不复制它们。

面向模型的层刻意做小：项目摘要受硬性 token 预算约束，工具聚焦，写入显式。没有隐藏的摘要，没有自动记忆提取，也没有网络依赖。

安装

从本地 checkout（开发）

cd /path/to/dsh-projectflow
pnpm install
pnpm build

Create a disposable test profile from the shipped web template.
dsh --profile dev --from-default-profile web

Use the file: protocol for a local package. This avoids pnpm's "linked
dependency will not resolve peers" advisory and installs the built package.
dsh plugin --profile dev add "file:$PWD"

dsh --profile dev --dump-config | grep -A2 projectflow
dsh --profile dev

最后一条命令启动 Web UI。项目工作区入口在侧边栏页脚，位于常规 Workspaces 区域下方，标签为 Project workspaces。

从 GitHub release / npm

release tarball
dsh plugin --profile <profile> add https://github.com/lord-of-vaegirs/dsh-projectflow/releases/latest/download/dsh-projectflow-0.2.0.tgz

or npm, once published
dsh plugin --profile <profile> add dsh-projectflow

or the GitHub source (pnpm runs the package prepare build)
dsh plugin --profile <profile> add github:lord-of-vaegirs/dsh-projectflow

包声明 engines.dsh 为 >=0.2.1-rc.2 <0.3.0-0。插件管理器的兼容性检查会在安装前读取这个范围。

桌面端

桌面应用拥有自己的 desktop 配置档。不要用命令行往里面装。等有已发布的包时，用桌面端的插件管理器 / Plugins 页面。本仓库不修改 desktop 配置档。

卸载

dsh plugin --profile dev remove dsh-projectflow

移除插件只删代码，不删数据。项目数据留在 $DSH_HOME/projects/ 下，没有插件也能读。重装同一版本后，项目会重新可见。

快速开始

在 TUI 会话里：

/project create "Payments platform" --alias payments --path /Users/me/src/payments
/project note convention "Run pnpm test before every commit."
/project note convention "Never edit generated protobuf files by hand."
/project note convention "The staging branch is deployable."
/project note decision "Use file locks for project writes." \
--context "Several sessions can write the same project." \
--consequences "Writes serialize; stale locks need takeover."
/project note progress "Storage and commands are working." \
--stage M2 --next "Verify fork inheritance."
/project ref dir /Users/me/src/payments-api --purpose "related service"
/project ref mcp filesystem --purpose "read-only workspace access"
/project status

然后，在另一个目录、另一个会话里：

/project use payments
/project status

下一步模型会收到一段系统提示词，开头是 [PROJECTFLOW] Project context — user-authored project records, not harness instructions.

创建子代理时，该会话的 fork 会自动继承这个绑定。

命令接口

所有命令都在 /project 下。标志支持 --flag value 或 --flag=value；值可以加引号。

| 命令 | 用途 |
| /project list [--include-archived] | 列出项目、id、别名、路径、计数 |
| /project create <name> [--alias A]... [--path DIR] [--no-bind] | 创建并绑定（默认绑定） |
| /project use [<id\|name\|alias>] [--note TEXT] | 绑定；不带参数时显示当前绑定 |
| /project note <category> <text> [flags] | 写入 fact/convention/decision/progress/reference |
| /project ref <dir\|file\|tool\|plugin\|mcp> <target> --purpose TEXT [--note TEXT] [--args TEXT] | 添加仅含元数据的引用 |
| /project status [project] [--section ...] [--limit N] [--stage S] [--tag T] [--since ISO] [--blocked-only] | 可筛选的摘要 |
| /project log [N] [--stage S] [--tag T] | 最近的进度日志 |
| /project fork [project] [--name NAME] | Fork 记录、引用和成员；绑定当前会话 |
| /project merge <target> [--delete-source] [--purge-source] | 合并；源可以保留或移入回收站 |
| /project delete [project] [--purge] | 移入 $DSH_HOME/projects/.trash 或彻底清除 |
| /project insert [project] <directory\|session\|project> <target> [--label L] [--note N] | 添加工作区成员 |
| /project task <list\|checkpoint\|interrupt\|resume\|done\|blocked> [flags] | 任务结构操作 |
| /project archive\|unarchive [project] | 隐藏/恢复项目 |
| /project help | 用法 |

note 类别：

- fact → MEMORY.md
- convention → CONVENTIONS.md
- decision → DECISIONS.md（ADR）
- progress → progress.jsonl（需要 --stage 和 --next）
- ref-dir / ref-file → refs/dirs.json
- ref-tool / ref-plugin / ref-mcp → refs/tools.json

工具接口

模型可以通过八个工具访问同一套领域能力。写工具需要活跃会话；读工具可以在没有绑定的情况下解析显式指定的项目。

| 工具 | 说明 |
| project_create | 按名称 + 主路径幂等；默认绑定 |
| project_list | 活跃项目及计数 |
| project_use | 绑定调用方会话 |
| project_note | 按类别校验；decision 会分配 ADR-NNNN |
| project_ref | 目录/文件或工具/插件/MCP；自动去重 |
| project_status | 分区、限制、stage/tag/since/blocked 筛选 |
| project_workspace | insert、remove-member、fork、merge、delete、archive、unarchive |
| project_task | list、checkpoint、interrupt、resume、done、blocked |
参数用 Zod 校验；校验失败会带上 code、message 和 next action。模型从引用里拿不到文件内容，只能拿到记录下来的元数据。

模型驱动的引用

注入的项目段落会明确告诉模型：工作过程中如果发现与项目相关的目录、文件、工具、插件或 MCP 服务器，可以调用 project_ref。这是模型自己决定，不是自动扫描。引用只是元数据：插件不会复制、挂载、启用或执行被引用的条目。模型仍可通过常规工具读取被引用的文件，受当前 DSH 沙箱约束。

项目工作区

项目专属会话

每个项目在 $DSH_HOME/projects/<projectId>/workspace/ 下有一个专属的 DSH 会话工作区。项目面板会列出该工作区里的会话，点 New project conversation 就在那里新建一个。工作区以项目名注册到 DSH，所以会话头部选中的是项目工作区，不是源目录。

DSH 0.2.1 仍要求每个 Session 都有 cwd；内部工作区就是这个 cwd。它刻意保持为空。真实的源目录、文件、工具、插件和 MCP 服务器都由 project_ref 表示。内部工作区也会出现在常规的 DSH Workspaces 树里，因为当前版本宿主没有虚拟工作区／隐藏 API。

每个项目有一个主工作区路径，以及任意数量的成员：

- directory —— 关联到项目的另一个文件夹；
- session —— 一个 DSH 会话 id，标题／工作区由调用方记录；
- project —— 指向另一个项目的成员边。

插入成员时只在 workspaces.json 里存引用，不复制、不移动、不检出任何文件。New project conversation 会在项目的内部会话工作区里创建 Session 并绑定到项目；源主路径仍是引用目标，不是会话 cwd。

Fork 把项目记录（memory、conventions、decisions、refs、progress、members）复制到新项目，带新 id 和 forkedFrom。它不复制会话绑定，也不复制任务执行状态。

Merge 合并记录，并按内容去重：

- memory/conventions 按规范化后的正文去重；
- decisions 按决策文本去重，需要时分配新的 ADR id；
- progress 按 timestamp/session/stage/text 去重；
- refs 取并集；
- 项目成员合并；源项目被删除时移除对它的引用；
- 加 --delete-source 时，源项目移到 $DSH_HOME/projects/.trash/...（软删除）。--purge-source 是破坏性形式。

Delete 默认进回收站。工作区目录里的内容一概不删。

数据模型

$DSH_HOME/projects/
<projectId>/
project.json # schemaVersion, id, name, aliases, timestamps, archived, primaryPath,
forkedFrom, mergedFrom
MEMORY.md # 稳定事实，条目以 § 分隔 CONVENTIONS.md # 规则，条目以 § 分隔 DECISIONS.md # ADR，以 § 分隔 refs/ dirs.json # [{kind:dir|file, path, purpose, note, addedAt, addedBy}] tools.json # [{kind:tool|plugin|mcp, tool, args, purpose, note, addedAt, addedBy}] progress.jsonl # 每行一个 JSON 对象 sessions.json # sessionId -> {boundAt, parentSessionId?, workspacePath?, note?} tasks.json # schemaVersion + 任务记录（checkpoint/status/pendingPrompt） workspaces.json # 主路径 + 目录/会话/项目成员 archive/ # 归档条目和 archive/index.json 指针 .lock # 短时写入锁 .trash/ # 软删除的项目目录 .registry.lock # 短时项目创建锁

$DSH_HOME 已设置时解析为 $DSH_HOME，否则解析为 ~/.dsh。config.projectsDir 可以用绝对路径覆盖根目录，供测试或部署使用。项目存储从不使用当前工作目录。

project.json

{
"schemaVersion": 1,
"id": "prj_7fa81facdd757f5c0a70c462947edee4",
"name": "Payments platform",
"aliases": ["payments"],
"createdAt": "2026-10-28T06:18:52.069Z",
"updatedAt": "2026-10-28T06:22:55.009Z",
"archived": false,
"primaryPath": "/Users/me/src/payments",
"forkedFrom": "prj_...",
"mergedFrom": ["prj_..."]
}

Markdown 条目

Always run the test suite before publishing.

§

DECISIONS.md 使用 pf-decision 和 ADR 正文：

ADR-0001: Use O_EXCL file locks for every project write.

- Date: 2026-10-28
- Status: accepted
- Context: Multiple sessions can write concurrently.
- Decision: Use O_EXCL file locks for every project write.
- Consequences: Writes serialize; stale locks need takeover.

§

单独一行的 § 是分隔符。用户内容里单独一行的 § 会被拒绝，这样协议不会产生歧义；把 § 留在句子内部，或者拆开条目。

progress.jsonl

{"ts":"2026-10-28T06:21:44.673Z","sessionId":"...","stage":"M2","did":"Verified TUI command path.","next":"Verify fork inheritance.","tags":[]}

blocked 可选。读取最近进度时显示最新五条；project_status 可以按阶段、标签、时间和阻塞状态过滤。

引用只是元数据

project_ref dir /path 只存路径字符串。它不读取、不复制、不同步、不监视那个目录。project_ref mcp filesystem 只存 MCP 名称和可选参数；它不启动、不调用、不内嵌服务器。工具引用和插件引用同理。不执行代码，也不复制原型。

架构

flowchart TB
User[User] -->|/project| Cmd[Command adapter]
Model[Model] -->|project_* tools| Tool[Tool adapters]
Desktop[Web / Desktop panel] -->|RPC /projectflow| Rpc[Host RPC bridge]
Cmd --> Service[ProjectService]
Tool --> Service
Rpc --> Service
Service --> Store[ProjectStore]
Service --> Binding[Binding + fork inheritance]
Service --> Task[Task checkpoint service]
Store --> Fs[(DSH_HOME/projects)]
Service --> Render[Context renderer + token budget]
Render --> Prompt[system-prompt/assemble waterfall]
Prompt --> Model
Prompt -.coexist.-> Mnemon[dsh-mnemon sections]

关键集成点，已对照 DSH 0.2.1-rc.2 验证：

- system-prompt/assemble waterfall —— 追加 projectflow:context 段，并设 interpolate: false；其他插件的段会保留。
- agent/created —— 在子会话收到第一条提示词之前，从 session.header.parentSession 生成子会话的绑定。
- session/event（turn/start、turn/end）—— 给当前任务打检查点，不会每写一个 token 就落盘。
- ctx.tools.register / ctx.commands.register —— 分别面向模型和人的入口。
- /projectflow 上带鉴权前缀的 Web 路由（准入走 connection.admit）—— 可选的浏览器桥接。

渲染器是同步的、纯的，且有预算上限。它不访问网络，也不自己调用模型。

模块边界见 docs/ARCHITECTURE.md，共存规则见 mnemon 边界。

任务调度语义

任务记录刻意做成操作系统风格：

{
"id": "task_...",
"sessionId": "...",
"status": "running",
"source": "user",
"checkpoint": {
"summary": "...",
"did": "...",
"next": "...",
"blocked": "",
"lastTool": "bash",
"pendingTools": [],
"turn": 2,
"step": 3,
"updatedAt": "..."
}
}

行为：

- 自动检查点在绑定会话的 turn/start 和 turn/end 时运行。它读取实时会话日志，取最新的用户/助手文本、最后一个工具，以及尚未完成的工具调用。
- project_task interrupt --prompt "..." 先写检查点，把提示词存到任务上，再协作式取消当前轮次（agent.cancel({kind:'hook'})）。下一次系统提示词组装会带上 [SYSTEM INJECTION] 和检查点，于是模型下一步就能看到这条紧急指令，以及工作停在哪里。
- resume / done / blocked 更新任务状态；list 显示记录。
- 用户命令从不抢占正在运行的工具。 /project 是命令入口：它在命令边界执行，产生的上下文出现在下一次提示词组装时。对用户提示词来说，这是安全的行为。
- 中断是协作式的。它不会杀掉 shell 进程，也不会硬取消任务；这条边界归 DSH 的取消语义管。如果正在运行的工具不响应取消，轮次就按 DSH 的策略收尾。
这是所要求的「系统提示词中断 vs 用户提示词等待」行为在 DSH 里的实际映射。真正的抢占式调度器无法只靠插件安全实现，因为它需要掌控 DSH 的轮次与工具生命周期。

浏览器 / 桌面面板

客户端 bundle 注册了以下内容：

- sidebar.footer.action，id 为 projectflow —— 侧边栏页脚里的 Project workspaces 操作，位置在常规 Workspaces 区域下方。这是 DSH 0.2.1-rc.2 中可用的稳定位置；sidebar.workspaces 座位是单占位槽，归 ui-workspace 所有，替换它就会移除常规会话浏览器。
- main，键为 projectflow —— 完整的项目工作区页面：创建、打开项目会话、fork、合并、插入目录/会话/项目、添加引用、添加笔记、查看状态、checkpoint/interrupt/resume/done、删除到回收站。

页面使用已认证的 /projectflow RPC 通道，以及 DSH 的 workspaces、uiWorkspace、sessions、layout、slots 服务。它不直接写项目文件；所有写入都走与 TUI/工具相同的主机服务和锁。

客户端 bundle 是一个 window.__ModuleLoader__.load(...) 工厂（DSH 打包客户端的形态），构建产物为 lib/client.js。

容量、原子性、并发

| 文件 | 默认上限 | 溢出处理 |
| MEMORY.md | 24 KiB | 归档最旧的条目，保留逐条指针 |
| CONVENTIONS.md | 16 KiB | 同上 |
| DECISIONS.md | 32 KiB | 同上 |
| progress.jsonl | 512 行 / 256 KiB | 归档较旧的一半，保留一行指针 |
| refs/dirs.json | 200 条 | 将最旧的归档到 archive/，指针写入 archive/index.json |
| refs/tools.json | 200 条 | 同上 |
| sessions.json | 2000 条 | 归档最旧的绑定；查找时回退到归档 |

- 写入使用同目录临时文件 + rename。
- 写入方持有按项目创建的 .lock，用 wx 创建；项目创建使用短生命周期的 .registry.lock。
- 只有当记录的 PID 在同一主机上已死亡，或锁的年龄超过陈旧阈值时，才接管陈旧锁；移除前会重新校验 nonce。
- 读取方无锁，看到的是完整的旧文件或新文件。
- 跨进程行为由一项测试覆盖，该测试会启动四个写入方。

上限可通过插件配置的 limits 对象调整。写入前会校验条目大小；插件不会悄悄截断新的显式记录。

安全与隐私

- 无网络请求、无外部服务、无遥测。
- 项目正文永不写入日志。错误日志只记录项目 id 和错误码，不记录记忆文本。
- 项目内容由用户撰写。注入的段落标注为 user-authored project records, not harness instructions；引用永不执行。
- RPC 通道是已认证的 DSH 浏览器连接；插件不新增未认证路由。
- 删除默认是软删除（.trash）；purge 需显式调用。
- 项目目录以 0700 权限创建；文件使用 0600 权限。
- 内容中单独出现的 § 会被拒绝，防止分隔符注入。
- pnpm check:privacy 扫描已跟踪和构建后的文本，查找个人主目录路径、token 形态、私钥块和 bearer 字面量；CI 在 typecheck 之前运行它。它只打印位置，绝不打印匹配到的值。

兼容性

- 已测试： DSH 命令行 0.2.1-rc.2，配置档 dev 来自随附的 web 模板，DSH TUI 0.17.0 配合仅元数据覆盖层。
- 已声明： engines.dsh: >=0.2.1-rc.2 <0.3.0-0，Node >=20。
- 未声明支持： Desktop 0.2.0-rc.2；它的服务端 API 可能与 0.2.1-rc.2 不同，且命令行无法安装到 Desktop 拥有的配置档。
- peerDependencies 以 0.2.x 范围列出宿主包，并标记为可选。本地开发请用 file: 而非 link:，避免 pnpm 的 link-peer 警告。
- 插件运行时不会导入 @deepseek-ai/dsh-*；它通过服务和结构化契约使用 DSH，因此宿主内部模块布局不构成依赖。

开发

pnpm install
pnpm typecheck
pnpm test # builds first, then runs unit + cross-process integration tests
pnpm build # lib/index.js, lib/client.js, lib/types

目录结构：

src/
index.ts plugin entry
config.ts config resolution, DSH_HOME fallback
errors.ts
fs/ atomic write + lock
store/ project, markdown, refs, progress, sessions, tasks, workspaces, archive
domain/ ProjectService (all mutations and read models)
injection/ token estimate + bounded renderer
dsh/ tools, commands, prompt waterfall, RPC bridge, structural contracts
client/ browser panel + RPC client
tests/ unit, integration, cross-process, client SSR
scripts/build.mjs esbuild host/client + tsc declarations

构建说明：

- 宿主包是 ESM，将 zod 外部化。
- 客户端包是 CJS，包装在 DSH ModuleLoader 工厂中，将 React 和 DSH 客户端包外部化。
- cordis.patch.yml 插入一行 projectflow。

测试

当前测试套件：24 个测试 / 12 个文件，包括：

- 跨进程写入串行化；
- 原子项目创建且不写入工作区；
- 带指针行的容量归档；
- 绑定、重新绑定、fork 继承、不猜测 cwd；
- 合并去重与成员清理；
- 上下文预算硬限制（英文和 CJK）；
- 系统提示词贡献与 mnemon 共存（保留段落）；
- 工具/命令/RPC 适配器；
- 客户端注册与 SSR 外壳；
- 任务检查点/中断/待处理提示词注入。

运行：

pnpm check:privacy
pnpm test

GUI 冒烟测试（需要运行中的 dev Web URL 和本地 Chrome）：

node scripts/gui-smoke.mjs 'http://127.0.0.1:3080/?token=...'

已执行的实时检查：

dsh --profile dev --from-default-profile webbash
dsh plugin --profile dev add "file:$PWD"
dsh --profile dev --dump-config | grep -A2 projectflow
dsh --profile dev

用只含元数据的覆盖层做 TUI 命令检查： bash
dsh --profile dsh-tui --patch /tmp/pf-tui-overlay.yml
/project create TUIProject --path "$PWD"
/project note convention "..."
/project status --section refs --section progress

验收清单和实测结果见 docs/ACCEPTANCE.md。

已知限制与路线图

当前限制

- 浏览器入口放在侧边栏页脚，而不是每个 Workspaces 分组下的嵌套区块；DSH 0.2.1-rc.2 在那里没有暴露稳定的子级位置。
- 中断是协作式的（agent.cancel），不是强制杀进程。
- 已有模型轮次的自动检查点；排队中的恢复轮次还没有自动调度。resume 需要显式调用。
- 会话绑定使用每个项目各自的 sessions.json；目前还没有全局反向索引。项目数量多时，用短 TTL 缓存加一次扫描。
- fork 在创建子级时继承父级绑定；父级之后重新绑定，不会回溯改变子级。
- 软删除的项目会留在 .trash 里，直到清除。目前还没有垃圾回收界面。

P1 候选

- 可选、默认关闭：把项目记忆镜像到 dsh-mnemon Memory Space。
- 项目目录的 zip 导出/导入。
- 项目时间线/关系图可视化。
- 面向大型安装的根会话→项目索引。
- 项目工作区之间的会话转移，以及真正的恢复队列。
- 硬归档压缩和回收站保留策略。

许可证

MIT。见 LICENSE。