@xirang-ai/dsh-teamflow 0.1.1 → 0.1.3

package/README.en.md

@@ -4,12 +4,12 @@
 
 Teamflow (`@xirang-ai/dsh-teamflow`) is a [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (DSH) plugin that turns **requirements → high-level design → detailed design → stories → development runs → bug fixes** into a persistent, resumable pipeline. It also adds a team workbench called **Xirang Workbench** to the DSH Web UI.
 
-Version: **`0.1.1`** (adds drag and drop to the create page attachments; see [CHANGELOG.md](CHANGELOG.md)).
+Version: **`0.1.3`** (detailed-design documents can be deleted individually; the workbench header shows the plugin version; see [CHANGELOG.md](CHANGELOG.md)).
 
-- Data lives in SQLite; documents live in the workspace, so closing a session does not lose progress.
+- Data lives in SQLite; documents live in the plugin directory (default `<dataDir>/docs`), so closing a session does not lose progress.
 - Five agent presets cover requirements, stories, bugs, development, and detailed design. Each preset controls its own tool boundary.
 - The workbench provides lists, detail pages, a flow chart, a create page, a read-only session tab, and guarded deletion.
-- Nineteen `teamflow_*` tools write interview and development results back to the database and workspace documents.
+- Twenty-one `teamflow_*` tools write interview and development results back to the database and plugin documents.
 
 ## Requirements
 
@@ -67,7 +67,7 @@ dsh plugin --profile web remove @xirang-ai/dsh-teamflow
 
 - **Lists**: four views (open / in progress / ready / completed) across requirements, standalone stories, and bugs.
 - **Requirement detail**: high-level design, detailed-design file tree, story list, execution flow chart, linked sessions, and a properties panel.
-- **Story / bug detail**: body, status, run history, and manual actions such as run, cancel, and complete.
+- **Story / bug detail**: body, status, run history, discussion sessions, and manual actions such as discuss, run, cancel, and complete.
 - **Three permission tiers**: the **Run** button on a story row, the story page, and the bug page has an arrow menu for **Normal run / Read-only run / Full permission run**. The main button always starts a normal run; the choice is not remembered, so picking full permission once does not carry over. The session starts with the matching sandbox mode and approval policy, and its header shows a short Normal / Read-only / Full badge (sessions started before this feature have no record and show no badge).
 - **Create page**: pick a type and workspace to start a session without choosing an agent manually. Files can be attached too: the attachment card is both a click target and a drop zone, and a drop goes through the same rules as a picker selection (images are checked against the same rules the session composer uses — type, per-file size, count and total taken from `ctx.attachments.imageLimits`, never a second list defined here; other file types carry no extra limits), with a reason for every refused file. Each picked file can be removed, and the submission sends them as attachments on the new conversation's first message next to the workspace and description. The submit button is held back until uploading finishes so no attachment is lost.
 - **Composer type picker**: an empty session switches between requirement / story / bug; a discussion session started from a requirement detail also offers requirement & outline / detailed design / story splitting.
@@ -79,14 +79,16 @@ dsh plugin --profile web remove @xirang-ai/dsh-teamflow
 | Item | Location |
 | --- | --- |
 | Database | `$DSH_HOME/xirang-ai/dsh-teamflow/teamflow.sqlite` |
-| Requirement / high-level design | `<workspace>/.xirang-ai/dsh-teamflow/requirements/<req>/requirement.md` |
-| Detailed design | `<workspace>/.xirang-ai/dsh-teamflow/requirements/<req>/docs/<doc>.md` |
-| Story | `<workspace>/.xirang-ai/dsh-teamflow/stories/<story>/story.md` |
-| Bug | `<workspace>/.xirang-ai/dsh-teamflow/bugs/<bug>/bug.md` |
+| Document root | `$DSH_HOME/xirang-ai/dsh-teamflow/docs` (override with `docsDir`) |
+| Requirement / high-level design | `<docs>/requirements/<req>/requirement.md` |
+| Detailed design | `<docs>/requirements/<req>/docs/<doc>.md` |
+| Story | `<docs>/stories/<story>/story.md` |
+| Bug | `<docs>/bugs/<bug>/bug.md` |
 
-- The workspace root `.gitignore` gets an `.xirang-ai/` entry automatically, so documents stay out of version control by default.
-- The schema version lives in `PRAGMA user_version` and is currently `16`. Migrations run at startup; a database newer than the installed plugin refuses to start.
-- Back up `teamflow.sqlite` and `.xirang-ai/dsh-teamflow/` before upgrading or reinstalling.
+- Documents live next to the database, both owned by the plugin: the user's project repository never gets a `.xirang-ai/` directory and its `.gitignore` is never rewritten. Keep the plugin directory when switching workspaces or machines.
+- The schema version lives in `PRAGMA user_version` and is currently `17`. Migrations run at startup; a database newer than the installed plugin refuses to start.
+- Back up `teamflow.sqlite` and `docs/` (or the configured `docsDir`) before upgrading or reinstalling.
+- Older versions stored bodies under the workspace's `.xirang-ai/dsh-teamflow/`. Upgrading neither moves nor reads those documents; move them into the document root by hand if you still need them.
 
 ## Configuration
 
@@ -95,6 +97,7 @@ The bundle config layer provides these defaults:
 | Field | Type | Default | Description |
 | --- | --- | --- | --- |
 | `dataDir` | string | `''` | Data directory; empty means `$DSH_HOME/xirang-ai/dsh-teamflow`. Supports `~`. |
+| `docsDir` | string | `''` | Document root; empty means `<dataDir>/docs`. Accepts absolute paths, paths relative to the working directory, and `~/`. |
 | `busyTimeoutMs` | number | `5000` | SQLite `busy_timeout` for concurrent writers (0–60000). |
 
 To override them, edit the user config layer of the current profile, for example `$DSH_HOME/profiles/web/cordis.patch.yml`:
@@ -104,6 +107,7 @@ To override them, edit the user config layer of the current profile, for example
   name: "@xirang-ai/dsh-teamflow"
   config:
     dataDir: "~/teamflow-data"
+    docsDir: "~/teamflow-docs"
     busyTimeoutMs: 10000
 ```
 

package/README.md

@@ -4,12 +4,12 @@
 
 Teamflow（`@xirang-ai/dsh-teamflow`）是 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（下称 DSH）的插件：把**需求 → 概要设计 → 详细设计 → 故事拆分 → 研发执行 → 缺陷修复**做成一条可持久化、可断点续跑的流水线，并在 Web 端提供团队工作台「息壤工作台」。
 
-当前版本：**`0.1.1`**（新增创建页附件拖放，变更记录见 [CHANGELOG.md](CHANGELOG.md)）。
+当前版本：**`0.1.3`**（详细设计文档可单独删除，工作台首页显示版本号，变更记录见 [CHANGELOG.md](CHANGELOG.md)）。
 
-- 数据落在 SQLite，文档落在工作区，关掉会话不丢进度。
+- 数据落在 SQLite，文档落在插件目录（默认 `<dataDir>/docs`），关掉会话不丢进度。
 - 五个 Agent 预设分别负责需求、故事、缺陷、研发和详细设计，工具边界由预设控制。
 - 工作台提供列表、详情、流程图、创建页、会话内只读页签，以及受控的删除入口。
-- 十九个 `teamflow_*` 工具把访谈与研发结果写回数据库和工作区文档。
+- 二十一个 `teamflow_*` 工具把访谈与研发结果写回数据库和插件文档。
 
 ## 环境要求
 
@@ -67,7 +67,7 @@ dsh plugin --profile web remove @xirang-ai/dsh-teamflow
 
 - **列表**：未完成 / 执行中 / 待开始 / 已完成四个视图；需求、独立故事、缺陷分组展示。
 - **需求详情**：概设正文、详设文件树、故事列表、执行流程图、关联会话和属性面板。
-- **故事 / 缺陷详情**：正文、状态、运行记录，以及执行、取消、完成等人工动作。
+- **故事 / 缺陷详情**：正文、状态、运行记录、讨论会话列表，以及讨论、执行、取消、完成等人工动作。
 - **三档权限执行**：需求详情的故事行、故事页、缺陷页三处的「执行」按钮右侧带箭头菜单，可选「普通执行 / 仅查看执行 / 完全权限执行」。主按钮直接按「普通执行」启动；默认档不记忆，上一次选「完全权限执行」也不会留到下一次。会话以对应沙箱模式与审批策略启动，会话头部显示「普通 / 仅查看 / 完全权限」短标签（旧会话没有记录，不显示）。
 - **创建页**：选类型和工作区后直接开新会话，不需要手动挑 Agent。还可以附带文件：附件区整块可点击选择，也可以把文件直接拖进附件卡片，拖放与点选走同一套规则（图片按宿主会话上传的同一套规则校验，类型、单张大小、条数与总大小取自 `ctx.attachments.imageLimits`，不在本页另立白名单；其它类型的文件不设额外限制），不合规的文件逐条给出原因；已选文件可逐个移除，提交时与工作区、描述一起作为第一条消息的附件发进新会话。附件上传完成前提交按钮会拦住，避免丢附件。
 - **输入框「创建类型」**：空白会话下可切换需求 / 故事 / 缺陷；从需求详情发起的讨论会话还会显示「需求与概要设计」/「详细设计」/「故事拆分」，用于继续对应的讨论。
@@ -79,14 +79,16 @@ dsh plugin --profile web remove @xirang-ai/dsh-teamflow
 | 项 | 位置 |
 | --- | --- |
 | 数据库 | `$DSH_HOME/xirang-ai/dsh-teamflow/teamflow.sqlite` |
-| 需求 / 概设 | `<workspace>/.xirang-ai/dsh-teamflow/requirements/<req>/requirement.md` |
-| 详细设计 | `<workspace>/.xirang-ai/dsh-teamflow/requirements/<req>/docs/<doc>.md` |
-| 故事 | `<workspace>/.xirang-ai/dsh-teamflow/stories/<story>/story.md` |
-| 缺陷 | `<workspace>/.xirang-ai/dsh-teamflow/bugs/<bug>/bug.md` |
+| 文档根 | `$DSH_HOME/xirang-ai/dsh-teamflow/docs`（可用 `docsDir` 改到别处） |
+| 需求 / 概设 | `<docs>/requirements/<req>/requirement.md` |
+| 详细设计 | `<docs>/requirements/<req>/docs/<doc>.md` |
+| 故事 | `<docs>/stories/<story>/story.md` |
+| 缺陷 | `<docs>/bugs/<bug>/bug.md` |
 
-- 工作区根 `.gitignore` 会自动追加 `.xirang-ai/`，文档默认不进版本库。
-- 数据结构版本写在 `PRAGMA user_version`，当前为 `16`；启动时自动迁移，结构版本高于当前插件时拒绝启动。
-- 升级或重装前建议备份 `teamflow.sqlite` 与 `.xirang-ai/dsh-teamflow/`。
+- 文档与数据库同根，都归插件目录所有：用户项目仓库里不会出现 `.xirang-ai/`，也不会改写工作区 `.gitignore`。换工作区或换机器时，保留插件目录里的数据库与文档即可。
+- 数据结构版本写在 `PRAGMA user_version`，当前为 `17`；启动时自动迁移，结构版本高于当前插件时拒绝启动。
+- 升级或重装前备份 `teamflow.sqlite` 与 `docs/`（自定义了 `docsDir` 时备份该目录）。
+- 旧版本把正文放在工作区 `.xirang-ai/dsh-teamflow/` 下；升级后这些文档不会被自动搬迁，也不会再按旧路径读取，需要时请手动移入文档根。
 
 ## 配置
 
@@ -95,6 +97,7 @@ dsh plugin --profile web remove @xirang-ai/dsh-teamflow
 | 字段 | 类型 | 默认 | 说明 |
 | --- | --- | --- | --- |
 | `dataDir` | string | `''` | 数据目录；留空表示 `$DSH_HOME/xirang-ai/dsh-teamflow`，支持 `~` |
+| `docsDir` | string | `''` | 文档根；留空表示 `<dataDir>/docs`，支持绝对路径、相对路径与 `~/` |
 | `busyTimeoutMs` | number | `5000` | SQLite `busy_timeout`，多会话并发写时的等待上限（0–60000） |
 
 要覆盖默认值，编辑当前 profile 的用户配置层，例如 `$DSH_HOME/profiles/web/cordis.patch.yml`：
@@ -104,6 +107,7 @@ dsh plugin --profile web remove @xirang-ai/dsh-teamflow
   name: "@xirang-ai/dsh-teamflow"
   config:
     dataDir: "~/teamflow-data"
+    docsDir: "~/teamflow-docs"
     busyTimeoutMs: 10000
 ```
 

package/RELEASE.md

@@ -9,7 +9,7 @@
 
 | 项 | 值 |
 | --- | --- |
-| 目标版本号 | **0.1.1**（用户已确认） |
+| 目标版本号 | **0.1.3**（用户已确认） |
 | 发布分支 / commit | 发布时填写 |
 | 发布日期 | 发布时填写 |
 | 发布人 | 发布时填写 |
@@ -17,7 +17,7 @@
 | dist-tag | `latest` |
 
 - [ ] 版本号已由开发者明确确认，且 `package.json`、`lib/client.js` banner、README / CHANGELOG 中的版本声明一致。
-- [ ] 发布后打 `v<version>` tag，并在 GitHub Release 写清配置、`engines.dsh` 与数据结构版本（当前 schema `16`）。
+- [ ] 发布后打 `v<version>` tag，并在 GitHub Release 写清配置、`engines.dsh` 与数据结构版本（当前 schema `17`）。
 
 ## 1. 与 DSH 官方 tag 的兼容性核对
 
@@ -78,7 +78,7 @@ npm pack --dry-run --json
 
 - [ ] 仓库内 `pnpm peers check` 无 `missing peer` / `unmet peer`。
 - [ ] 干净 profile 里 `pnpm peers check` 对 `@deepseek-ai/dsh-*` 宿主包报 `missing peer` 属预期：这些实例由正在运行的 DSH 提供，不要为了消除警告把它们改成 optional；以真实启动成功为准。
-- [ ] `npm pack --dry-run` 的 93 个文件中没有 `src/`、`test/`、`docs/`、`design/`、`.tmp/`、`.devhome/`、`.xirang-ai/`、`*.sqlite*`。
+- [ ] `npm pack --dry-run` 的 95 个文件中没有 `src/`、`test/`、`docs/`、`design/`、`.tmp/`、`.devhome/`、`.xirang-ai/`、`*.sqlite*`。
 - [ ] `prepublishOnly` 已配置为 `pnpm run verify`，干净 checkout 发布时会先构建。
 
 ## 3. 干净 profile 安装与真实启动
@@ -108,7 +108,7 @@ sqlite3 "$DSH_HOME/xirang-ai/dsh-teamflow/teamflow.sqlite" \
   'PRAGMA user_version; SELECT key, value FROM meta; SELECT key, name FROM roles;'
 ```
 
-- [ ] `PRAGMA user_version = 16`。
+- [ ] `PRAGMA user_version = 17`。
 - [ ] `meta.plugin_version` 等于 `package.json` 版本。
 - [ ] `roles` 含 `product` / `dev`。
 - [ ] 至少真实调用一次 `teamflow_*` 工具（含一次错误分支）。
@@ -125,7 +125,7 @@ sqlite3 "$DSH_HOME/xirang-ai/dsh-teamflow/teamflow.sqlite" \
 - [ ] 开发端口统一为 `3091`（与本文件、AGENTS.md §5.1 一致）。
 - [ ] README 中的链接均可访问；仓库根的 `docs/` 仅作为提示词一致性报告、快照、Demo 走查结论与历次发版检查留痕保留，不进入 npm 包。
 - [ ] 配置说明指向 **profile 配置层** 的 `id: teamflow` 覆盖，而不是让用户改 `node_modules` 里的包内文件。
-- [ ] 版本号、schema 版本、工具数量（当前 19 个）、预设数量（当前 5 个）与实际一致。
+- [ ] 版本号、schema 版本、工具数量（当前 21 个）、预设数量（当前 5 个）与实际一致。
 - [ ] 本文件已按本次发版更新；AGENTS.md 的阅读路径与文档索引没有死链。
 
 ## 5. 代码、敏感信息与数据卫生
@@ -157,7 +157,7 @@ find . -maxdepth 2 \( -name '*.sqlite*' -o -name '.tmp' -o -name '.devhome' -o -
 - [ ] Agent 人设 / prompt 中的语言与目标用户一致；新增语言时同时补字典、`normalizeLocale` 与测试。
 - [ ] `pnpm test` 中的 locale 测试通过。
 
-当前核对（2026-11-11）：en / zh 各 334 个键，集合一致、无空值；en 无中文残留；`src/remote` 的错误均走 `translate()`；客户端硬编码中文只出现在注释与验收标准正则中。
+当前核对（2026-11-11）：en / zh 各 336 个键，集合一致、无空值；en 无中文残留；`src/remote` 的错误均走 `translate()`；客户端硬编码中文只出现在注释与验收标准正则中。
 
 ## 7. Git、npm 与发布
 

package/cordis.patch.yml

@@ -28,6 +28,8 @@
       # Settings are the bundle's defaults; a profile patch can override them.
       config:
         dataDir: ''
+        # Empty keeps the document root at <dataDir>/docs, next to the database.
+        docsDir: ''
         busyTimeoutMs: 5000
 
     - id: preset-xirang-requirement
@@ -865,7 +867,7 @@
                 3. 需要确认某份详设该挂哪些故事时，用 teamflow_get_requirement 返回的故事列表核对标题与编号。你读不到故事正文，所以不要评论故事的验收标准细节。
                 4. 读完后先用两三句话概括：现有详设的结构、覆盖范围、与概要设计的对应关系。然后只问真正缺失或互相冲突的信息。
                 5. 讨论要围绕：接口、数据、状态机、异常与边界、权限、验收方式，以及文档之间的边界和一致性。
-                6. 文档粒度按 kind 自动划分：流程用 flow、数据用 data、接口用 interface、页面用 page、规则用 rule。一份文档只讲一件事；同一 kind 同一主题已有文档时更新既有文档，不要新建副本。这套分类由你按内容自动判定，不设确认闸口。
+                6. 文档粒度按 kind 自动划分：流程用 flow、数据用 data、接口用 interface、页面用 page、规则用 rule。一份文档只讲一件事；同一 kind 同一主题已有文档时更新既有文档，不要新建副本；用户明确要求「删旧建新」时，先删除旧文档再新建。这套分类由你按内容自动判定，不设确认闸口。
                 7. 一次最多问 3 个问题；能选择就给选项；不重复询问用户已经说过的内容。
 
                 ## 不做
@@ -882,7 +884,7 @@
 
                 遇到下列情况先停下说明并等用户回答，不要自行处置：
 
-                1. 写回前：先按「结论 / 理由 / 影响 / 待办」给出摘要，并明确问用户是否写回；用户确认后才调用 teamflow_create_design_doc 或 teamflow_update_design_doc。
+                1. 写回前：先按「结论 / 理由 / 影响 / 待办」给出摘要，并明确问用户是否写回；用户确认后才调用 teamflow_create_design_doc 或 teamflow_update_design_doc。删除文档前必须单独说明「正文文件与故事覆盖关系会一并删除、不可恢复」，得到明确同意后才调用 teamflow_delete_design_doc，一次只删一份。
                 2. 概要设计自相矛盾、或与用户新说法冲突时：指出冲突的具体两处，问以哪个为准，不要静默按一方写。
                 3. 需求已完成、已归档或已取消时：说明当前状态，问是否仍要在其上继续设计。
                 4. 用户要求改概设正文或拆故事时：说明不在你的职责内，并指出该走哪个入口。
@@ -901,7 +903,7 @@
 
                 1. 按职责内第 5 条的七个维度推进讨论，一次最多 3 个问题。
                 2. 形成结论时给出「结论 / 理由 / 影响 / 待办」摘要，并明确问是否写回。
-                3. 修改已有文档 → teamflow_update_design_doc（传文档 id）；新增文档 → teamflow_create_design_doc（定 kind、sortOrder、storyIds）。
+                3. 修改已有文档 → teamflow_update_design_doc（传文档 id）；新增文档 → teamflow_create_design_doc（定 kind、sortOrder、storyIds）；删除旧文档 → teamflow_delete_design_doc（传文档 id，先说明不可恢复）。
                 4. 写回后说明写了哪几份、各自路径，以及仍然未决的事项。
 
                 # 输入输出约定
@@ -918,6 +920,7 @@
                 2. 不要求用户手工粘贴文档内容。
                 3. 不在同一份文档里塞进多件互不相关的事。
                 4. 不用占位式 TODO 当作讨论结论。
+                5. 不一次删除多份文档，不用删除代替改写。
           - id: teamflow-tools
             name: '@xirang-ai/dsh-teamflow/tools'
             config: