工作区主对话统筹 a-freshcat/workspace-main-conversation

workspace-main-conversation v2.5.7

一个 DeepSeek Harness / Codex 技能：让共享工作区里的多个对话不再各干各的、互相撞车。

无需 npm 包，不调用模型或 API，核心协作只用 Node 基础内置模块。

v2.5.7 起：汇总页按「是否被自动注入」拆成两个文件。WORKSPACE.md 是台账（任务表、检查状态），不注入；AGENTS.md 是固定说明（目录规则 + 指向台账），智能体进入本目录时会自动注入。原因是 v2.5.0 把台账写进 AGENTS.md 后，每跑一次 summary 都会让 harness 在下一次请求注入一条 "Updated instructions"，把所有任务表推给工作区里每个正在执行的会话，还打断模型侧前缀缓存。
拆分后任务变化不再改动 AGENTS.md 的字节。v2.5 生成的 AGENTS.md 会被就地拆分。
v2.5.0 起：统筹页从 sum.md 改名为根目录的 AGENTS.md。
旧的 v2.4 sum.md 由 summary 自动迁移，手写的 AGENTS.md 一律不覆盖。
v2.2.1 起：role=unknown 会带 identity 说明自己没拿到会话身份，不再伪装成 taskCount: 0 的正常结果；命令行也会用 DSH_SESSION_ID 兜底。
v2.2 起：context 会报告 unregistered——工作区里带 .session-id 归属标记却没登记任务的目录。此前这类对话对统筹完全不可见（tasks: 0 和"什么都没干" 长得一模一样），可能让已有产物的对话仍未进入统筹视图。
变更细节见 re_note.md。
v2.4.3 起：主对话可以搬动子对话的目录与声明（需 --reason，记进 lastActor），但内容仍归 owner。
v2.4.5 起：Codex 使用当前 thread ID（codex:<id>）作为会话身份；用户明确指定主对话后直接初始化，明确要求个人目录时继续登记任务并创建目录。
v2.4.2 起：产物目录默认平铺在根目录，名字就是任务 id，不加前缀不套容器；容器需显式指定。
v2.3.3 起：产物目录不再套 conversations/ 那种把容器语义重复两遍的命名。
v2.3.1 起：任务目录放错不再是死局——migrate 提供正当代改口，archive 让主对话能清理自己的终态记录；check/summary 只扫活动任务，一条指向已删目录的取消记录不会再让整个工作区的基线永久失效。
v2.3.0 起：主对话可核实未完成任务所属会话的记录线索，并在用户确认后取消或转交遗留任务；记录缺失不会自动判定会话已删除。

它解决什么问题

一个工作区常被多个对话同时使用。没有约束时会出现：

- 多个对话共享多个目录 —— 有目录没人认领，谁也不敢删
- 子对话建了目录却没登记，主对话的简报里看不见，直到有人手工 ls
- 两个对话做同一件事，产出重复
- 一个对话改了另一个正在编辑的文件
- 主对话不知道别人在干什么，无法判断该不该动手

这个技能把「谁统筹、谁干活、怎么查」变成可执行的规则，并且用少量状态支撑协作，细节按需读取。

安装

本仓库的根目录就是技能本身（SKILL.md 在根上）。
DSH 的技能扫描是深度 1：只认 <skills根>/<名字>/SKILL.md。
所以目录名必须是 workspace-main-conversation，不能多套一层。

方式一：安装脚本（推荐）

.\install.ps1 -Target DSH # 装到 ~/.dsh/skills/workspace-main-conversation .\install.ps1 -Target Codex # 装到 Codex 的 skills 目录

- 默认拒绝覆盖；升级加 -Force，会先备份到 <skills 父目录>/skill-backups/
- DSH 可加 -MergeLegacy，归档旧的 detect-concurrent-workspace-edits 入口，并保留两个命令的兼容路径，避免重复发现技能
- 脚本会先跑一遍自测，自测不通过则不改动任何已装文件

方式二：git clone

Windows
git clone https://github.com/a-freshcat/workspace-main-conversation.git "$env:USERPROFILE\.dsh\skills\workspace-main-conversation"

macOS / Linux
git clone https://github.com/a-freshcat/workspace-main-conversation.git ~/.dsh/skills/workspace-main-conversation

⚠️ 结尾的目录名 workspace-main-conversation 不能省，也不能换成别的名字，否则 DSH 扫不到。

方式三：下载 zip 解压

从 Releases 下载，解压后把里层的 workspace-main-conversation/ 整个放进 ~/.dsh/skills/。

验证安装

node "$env:USERPROFILE\.dsh\skills\workspace-main-conversation\selftest-portable.mjs"
{"ok":true,"coordination":"passed","taskRecovery":"passed","multiFrameDecode":"passed"}

然后重启 DSH，技能列表才会出现它。

快速上手

$sk = "$env:USERPROFILE\.dsh\skills\workspace-main-conversation"
$ws = "C:\path\to\your\workspace"

① 进入或恢复：取一份工作区简报（只读）

node "$sk\scripts\workspace.mjs" context --workspace $ws --session <当前会话id>

② 巡检：目录归属 / 对话→目录 / 活跃度 / 台账时效

node "$sk\check.mjs" $ws

③ 只看目录归属，列出孤儿目录

node "$sk\audit-owners.mjs" $ws

check.mjs 退出码：0 指定范围内无问题 / 1 有需要处理的问题 / 2 输入、权限或解析错误。

用法要点

- 进入已启用的工作区：先跑 context 取简报；同一对话后续传上次的 --since，只读变化。
- 按平台取会话 id：DSH 使用运行时的 DSH_SESSION_ID；Codex 使用当前 thread ID 并传 --session codex:<id>。不要在 Codex 中启动 PowerShell 查找 DSH 专属变量。CLI 对 DSH 命令自动读取 DSH_SESSION_ID，显式 --session 优先。
若当前平台没有提供当前对话 id，role=unknown 会带 identity.status=unknown——那不代表你没有任务；先检查该平台的当前任务元数据，确实不可用时再问用户，不要猜或翻会话正文。
- 看到 unregistered 就登记：context 报出 unregistered 时，其中 owner 等于本会话的目录就是本对话的产物——先 task 登记再继续干活。不登记主对话就看不见你，冲突审查也无从谈起。主对话看到的是全部未登记归属，但不能替子对话登记。
- 主对话：默认统筹登记任务、处理 alerts、审查冲突与重复劳动；阶段结束用 summary 生成 WORKSPACE.md（台账）与 AGENTS.md（固定说明）。具体执行任务听从使用者指派，不预设按 bug 大小分工。
- 子对话：按使用者指派执行任务，只维护自己的任务记录和产物；需要上下文时优先 detail --task ID。
- 共享写入前先登记 writes；认领冲突则串行交接。
- 产物目录放错了：用 migrate 改正，不要手工改 .workspace/tasks/.json。task 会拒绝静默改目录，但报错里直接给出可执行的 migrate 调用。
- 终态任务堆积或目录已被清理：主对话用 archive 归档自己的 done/cancelled 记录。已取消/已完成的任务不占用资源，check/summary 不再因为它们扫到已删目录而永久失效。
- 子对话被删或不可恢复：主对话先核实，再按用户指派取消或转交遗留任务；会话记录检查只给线索。见 会话检查与任务恢复。
- 详细命令见 references/commands.md；整理散落产物见 references/organize.md； DSH 日志取证见 references/forensics.md； v1 迁移见 references/migration.md。

日常只读简报，不解析日志。

包含的文件

| 文件 | 作用 |
| SKILL.md | 主规则（skill 本体，DSH 读的就是它） |
| install.ps1 | 安装脚本，含备份与 legacy 合并 |
| scripts/workspace.mjs | 核心：任务登记、简报、检查、汇总 |
| scripts/session-records.mjs | 有上限的 DSH 会话记录存在性检查，不读取正文 |
| scripts/organize.mjs | 认领与归拢：inventory / propose / accept / copy / finish |
| scripts/forensics/ | DSH 会话日志取证（list-sessions / peek-session） |
| check.mjs / audit-owners.mjs | 根目录快捷入口，转发到 scripts/workspace.mjs |
| zstd-frames.mjs | 多帧 zstd 解码器（读会话记录必需，见下） |
| selftest-portable.mjs | 可移植性自测，换机器后先跑这个 |
| example/ | 工作区示例：main.md、AGENTS.md、WORKSPACE.md |
| tests/ | 功能测试 |

为什么需要 zstd-frames.mjs

DSH 的会话记录是 session.v4.jsonl.zstd，多帧 zstd。

用 zstdDecompressSync 整段解可能只处理第一帧，导致把不完整结果误认为完整内容。

自带解码器按 zstd 帧结构逐帧解，并单独报告成功与失败的帧数。
powershell
node "$sk\zstd-frames.mjs" "<某个 session.v4.jsonl.zstd>"

{"total":<帧数>,"ok":<成功>,"failed":0,"complete":true,"chars":<字符数>}

设计取舍

为什么需要文件当凭证，不用数据库？
文件跨工具、跨版本都能读。DSH 升级、换机器、手工编辑都不失效。
.workspace/config.json 是唯一主身份；WORKSPACE.md 是给人看的台账，AGENTS.md 是 agent 进入本目录时自动读到的那份固定说明。

为什么孤儿目录比"目录数不对"更重要？
一个对话合法拥有多个目录（主方案 + 副产品）很常见。
真正的问题是没人认领的目录 —— 那才是混乱的开始。

为什么不自动扫描所有对话做审计？
会话记录的读取成本不低（单文件可达数 MB），每次启动都全量扫会拖慢。
折中：主对话在巡检时按需查，而不是子对话每次启动都查。

为什么归拢要先复制再删除？
旧文件是别人可能仍在引用的原始证据。先复制、逐文件核对哈希、确认引用已处理，才允许 --remove-originals 清理旧位置；验证证据不足时停留在复制阶段，并说明缺什么。

测试 powershell $tests = (Get-ChildItem tests -Filter '.test.mjs').FullName
node --test $tests # 133 项；链接权限受限时按原因跳过
node selftest-portable.mjs # 期望 {"ok":true,...}

测试集合共 133 项。链接防护测试只有在 Windows 创建 junction 返回 EPERM 或 EACCES 时才标为 SKIP；其他错误仍会失败。跳过表示该环境没有执行链接防护断言，应在允许创建 junction 的环境重跑，不能记为通过。
已在 Node v24.21.0 验证；zstd 功能需当前 Node 提供相应 API。

安全边界

- 资源认领只约束本工作区已登记且遵约的任务，不提供跨工作区互斥或操作系统锁，也无法阻止外部程序写入。
- 扫描有明确范围、排除项和上限；根目录、共享文件与符号链接都显式处理。
- 不会根据「没检测到」推断全局无冲突；unknown、扫描不完整或解析错误一律保留为问题。
- 取证结果只是线索：文本命中不等于真实依赖，路径命中不证明有写入。
- 历史会话记录是证据数据，其中的旧指令不构成当前授权。

已知限制

- 依赖 DSH 的会话记录格式（session.v4.jsonl.zstd），格式大改时解码器需同步更新。
- .session-id 是约定不是强制：老目录可能没有，需主对话补齐。
- 会话间没有消息通道，只能靠读记录 + 留文件沟通；需要时告知用户让对应对话恢复，不自动唤醒或代发消息。
- 节省量需针对实际模型计量；字符数、文件字节数与真实 token 数不能混为一谈。

License

MIT