@xirang-ai/dsh-teamflow 0.1.1 → 0.1.2

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.2`** (documents move into the plugin directory; stories and bugs gain discussion sessions; 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 `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.2`**（文档迁入插件目录，故事与缺陷支持讨论会话，变更记录见 [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.2**（用户已确认） |
 | 发布分支 / 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 版本、工具数量（当前 20 个）、预设数量（当前 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

package/lib/client.js

@@ -1,4 +1,4 @@
-/* @xirang-ai/dsh-teamflow 0.1.1 — generated by scripts/build.mjs, do not edit. */
+/* @xirang-ai/dsh-teamflow 0.1.2 — generated by scripts/build.mjs, do not edit. */
 window.__ModuleLoader__.load({
 	id: "@xirang-ai/dsh-teamflow",
 	factory: (require) => {
@@ -341,6 +341,7 @@ window.__ModuleLoader__.load({
 		  "delete.statusMissing": "—",
 		  "delete.summary": "{total} record(s), {deletable} deletable",
 		  "detail.branch": "Branch",
+		  "detail.bugDiscussion": "Discuss this bug in a new session",
 		  "detail.bugBody": "What happened",
 		  "detail.completedAt": "Completed",
 		  "detail.description": "Description",
@@ -356,6 +357,7 @@ window.__ModuleLoader__.load({
 		  "detail.discussionNewDetail": "Discuss the detailed design in a new conversation",
 		  "detail.discussionNewSplit": "Split Stories in a new conversation",
 		  "detail.discussionOpen": "Open",
+		  "detail.storyDiscussion": "Discuss this story in a new session",
 		  "detail.discussionStarting": "Creating conversation…",
 		  "detail.docs": "Detailed design",
 		  "detail.docsEmpty": "No detailed design written yet.",
@@ -679,6 +681,7 @@ window.__ModuleLoader__.load({
 		  "delete.statusMissing": "—",
 		  "delete.summary": "共 {total} 条，可删除 {deletable} 条",
 		  "detail.branch": "分支",
+		  "detail.bugDiscussion": "在新会话中进行缺陷讨论",
 		  "detail.bugBody": "缺陷说明",
 		  "detail.completedAt": "完成时间",
 		  "detail.description": "故事说明",
@@ -694,6 +697,7 @@ window.__ModuleLoader__.load({
 		  "detail.discussionNewDetail": "在新会话中进行详细设计讨论",
 		  "detail.discussionNewSplit": "在新会话中进行故事拆分",
 		  "detail.discussionOpen": "打开",
+		  "detail.storyDiscussion": "在新会话中进行故事讨论",
 		  "detail.discussionStarting": "正在创建会话…",
 		  "detail.docs": "详细设计",
 		  "detail.docsEmpty": "还没有写详细设计。",
@@ -897,6 +901,7 @@ window.__ModuleLoader__.load({
 		  cancelStory: "cancelStory",
 		  completeBug: "completeBug",
 		  prepareRequirementSession: "prepareRequirementSession",
+		  prepareDiscussionSession: "prepareDiscussionSession",
 		  sessionPermissionTier: "sessionPermissionTier",
 		  previewDelete: "previewDelete",
 		  deleteRecords: "deleteRecords",
@@ -1034,6 +1039,21 @@ window.__ModuleLoader__.load({
 		    ]),
 		    result: JSON_CODEC
 		  }),
+		  Object.freeze({
+		    id: `${PACKAGE_NAME}#${METHODS.prepareDiscussionSession}`,
+		    service: SERVICE_KEY,
+		    namespace: NAMESPACE,
+		    method: METHODS.prepareDiscussionSession,
+		    invocation: { kind: "direct" },
+		    parameters: Object.freeze([
+		      parameter("subjectType", "Discussion subject: requirement, story or bug"),
+		      parameter("subjectId", "Requirement, story or defect the discussion belongs to"),
+		      parameter("sessionId", "Newly created conversation to link"),
+		      parameter("kind", "Discussion kind: discuss for stories and defects, the requirement kinds otherwise"),
+		      LOCALE_PARAMETER
+		    ]),
+		    result: JSON_CODEC
+		  }),
 		  Object.freeze({
 		    id: `${PACKAGE_NAME}#${METHODS.sessionPermissionTier}`,
 		    service: SERVICE_KEY,
@@ -1151,6 +1171,15 @@ window.__ModuleLoader__.load({
 		  }
 		  return ["【继续讨论需求与概要设计】", "", "我的补充："].join("\n");
 		}
+		var STORY_DISCUSSION_PRESET = "xirang-story";
+		var BUG_DISCUSSION_PRESET = "xirang-bug";
+		function presetForRecordDiscussion(kind) {
+		  return kind === "bug" ? BUG_DISCUSSION_PRESET : STORY_DISCUSSION_PRESET;
+		}
+		function buildRecordDiscussionPrompt(kind, title) {
+		  const heading = kind === "bug" ? "【继续讨论缺陷】" : "【继续讨论故事】";
+		  return [heading, title, "", "我的补充："].join("\n");
+		}
 
 		// src/client/composer-kind.ts
 		var COMPOSER_KINDS = [...CREATE_KINDS, "design", "detail", "split"];
@@ -2886,6 +2915,13 @@ window.__ModuleLoader__.load({
 		  const pad = (value2) => String(value2).padStart(2, "0");
 		  return `${pad(at.getMonth() + 1)}-${pad(at.getDate())} ${pad(at.getHours())}:${pad(at.getMinutes())}`;
 		}
+		function discussionNodes(sessions) {
+		  return sessions.map((session) => ({
+		    sessionId: session.sessionId,
+		    kind: session.kind,
+		    at: session.linkedAt ?? session.preparedAt ?? session.createdAt
+		  }));
+		}
 		var EMPTY_BOARD = { requirements: [], standalone: [], bugs: [] };
 		var STORY_RUNNING = ["developing", "self_testing"];
 		var STORY_DONE = ["done", "completed", "cancelled"];
@@ -3016,7 +3052,8 @@ window.__ModuleLoader__.load({
 		      acceptance: parsed.acceptance,
 		      bodyMissing: story.bodyMissing,
 		      ...last === void 0 ? {} : { lastRun: { status: last.status, at: last.at } },
-		      runs
+		      runs,
+		      sessions: discussionNodes(story.sessions)
 		    };
 		    if (story.requirementId === null) {
 		      standalone.push({ kind: "story", id: story.id, workspaceId: node.workspaceId, story: node });
@@ -3037,12 +3074,8 @@ window.__ModuleLoader__.load({
 		    const finished = stories.length > 0 && stories.every((story) => story.status === "completed");
 		    const state = requirement.status === "archived" ? "done" : running ? "running" : requirement.status === "completed" || finished ? "done" : "ready";
 		    const branch = runs.find((run) => run.branch.length > 0)?.branch;
-		    const sessions = snapshot.requirementSessions.filter((session) => session.requirementId === requirement.id).map(
-		      (session) => ({
-		        sessionId: session.sessionId,
-		        kind: session.kind,
-		        at: session.linkedAt ?? session.preparedAt ?? session.createdAt
-		      })
+		    const sessions = discussionNodes(
+		      snapshot.requirementSessions.filter((session) => session.requirementId === requirement.id)
 		    );
 		    const latestDesign = sessions.find((session) => session.kind === "design");
 		    return {
@@ -3081,7 +3114,8 @@ window.__ModuleLoader__.load({
 		      updatedAt: bug.updatedAt,
 		      ...last?.sessionId === void 0 ? {} : { sessionId: last.sessionId },
 		      ...bug.createSessionId === null ? {} : { createSessionId: bug.createSessionId },
-		      runs
+		      runs,
+		      sessions: discussionNodes(bug.sessions)
 		    };
 		  });
 		  return { requirements, standalone, bugs };
@@ -14108,6 +14142,7 @@ window.__ModuleLoader__.load({
 		  const [createBusy, setCreateBusy] = (0, import_react10.useState)(false);
 		  const [createError, setCreateError] = (0, import_react10.useState)(null);
 		  const [discussionBusy, setDiscussionBusy] = (0, import_react10.useState)(null);
+		  const [recordDiscussionBusy, setRecordDiscussionBusy] = (0, import_react10.useState)(null);
 		  const [cleanup, setCleanup] = (0, import_react10.useState)(false);
 		  const [selected2, setSelected] = (0, import_react10.useState)(/* @__PURE__ */ new Set());
 		  const [confirm, setConfirm] = (0, import_react10.useState)(null);
@@ -14611,14 +14646,59 @@ window.__ModuleLoader__.load({
 		    },
 		    [data, openConversation2, showToast, t]
 		  );
+		  const startRecordDiscussion = (0, import_react10.useCallback)(
+		    (subject) => {
+		      const open = openConversation2;
+		      if (open === void 0) {
+		        showToast(t("toast.startUnavailable"));
+		        return;
+		      }
+		      setRecordDiscussionBusy(subject.kind);
+		      open(subject.workspaceId, buildRecordDiscussionPrompt(subject.kind, subject.title), {
+		        agentPreset: presetForRecordDiscussion(subject.kind),
+		        autoSend: false,
+		        composerKind: subject.kind
+		      }).then(async (outcome) => {
+		        if (outcome.status === "unavailable") {
+		          if (mounted.current) {
+		            showToast(outcome.message ?? t("toast.discussionFailed", { title: subject.title }));
+		          }
+		          return;
+		        }
+		        if (outcome.sessionId === void 0) {
+		          if (mounted.current) {
+		            showToast(t("toast.discussionDrafted", { title: subject.title }));
+		          }
+		          return;
+		        }
+		        try {
+		          await data.prepareDiscussionSession(subject.kind, subject.id, outcome.sessionId, "discuss");
+		          if (!mounted.current) return;
+		          showToast(
+		            outcome.status === "drafted" ? t("toast.discussionDrafted", { title: subject.title }) : t("toast.discussionStarted", { title: subject.title })
+		          );
+		        } catch (failure) {
+		          if (!mounted.current) return;
+		          showToast(
+		            t("toast.discussionLinkFailed", {
+		              title: subject.title,
+		              message: failureMessage(failure)
+		            })
+		          );
+		        }
+		      }).catch(() => {
+		        if (mounted.current) showToast(t("toast.discussionFailed", { title: subject.title }));
+		      }).finally(() => {
+		        if (mounted.current) setRecordDiscussionBusy(null);
+		      });
+		    },
+		    [data, openConversation2, showToast, t]
+		  );
 		  const requirementAction = (0, import_react10.useCallback)(
 		    (requirement) => {
 		      if (requirement.state === "running") {
 		        return { label: t("row.open"), tone: "live", icon: ICONS.live };
 		      }
-		      if (requirement.state === "done") {
-		        return { label: t("row.history"), tone: "ghost", icon: ICONS.ghost };
-		      }
 		      const lone = loneReadyStory(requirement);
 		      return lone === void 0 ? null : { label: t("row.start"), tone: "soft", icon: ICONS.soft };
 		    },
@@ -14713,11 +14793,7 @@ window.__ModuleLoader__.load({
 		    }
 		  };
 		  const storyAction = (0, import_react10.useCallback)(
-		    (story) => {
-		      if (story.state === "running") return { label: t("row.open"), tone: "live", icon: ICONS.live };
-		      if (story.state === "done") return { label: t("row.history"), tone: "ghost", icon: ICONS.ghost };
-		      return { label: t("row.start"), tone: "soft", icon: ICONS.soft };
-		    },
+		    (story) => story.state === "ready" ? { label: t("row.start"), tone: "soft", icon: ICONS.soft } : null,
 		    [t]
 		  );
 		  const runStoryAction = (0, import_react10.useCallback)(
@@ -15243,7 +15319,14 @@ window.__ModuleLoader__.load({
 		          onDelete: () => openDelete([{ kind: "bug", id: activeBug.id }]),
 		          onComplete: () => setDecision({ kind: "complete-bug", bug: activeBug, busy: false, error: null }),
 		          onStartFix: (tier) => startBugFix(activeBug, tier),
-		          onCancelFix: () => cancelBugFix(activeBug)
+		          onCancelFix: () => cancelBugFix(activeBug),
+		          onNewDiscussion: () => startRecordDiscussion({
+		            kind: "bug",
+		            id: activeBug.id,
+		            title: activeBug.title,
+		            workspaceId: activeBug.workspaceId
+		          }),
+		          discussionBusy: recordDiscussionBusy === "bug"
 		        }
 		      ) : null,
 		      view.kind === "story" && activeStory !== void 0 ? /* @__PURE__ */ (0, import_jsx_runtime10.jsx)(
@@ -15263,7 +15346,14 @@ window.__ModuleLoader__.load({
 		          onCancelRun: () => setDecision({ kind: "cancel-run", story: activeStory, busy: false, error: null }),
 		          onOpenSession: (sessionId) => openSession(sessionId),
 		          onOpenPath: openFile,
-		          onMissing: (path) => showToast(t("doc.linkMissing", { path }))
+		          onMissing: (path) => showToast(t("doc.linkMissing", { path })),
+		          onNewDiscussion: () => startRecordDiscussion({
+		            kind: "story",
+		            id: activeStory.id,
+		            title: activeStory.title,
+		            workspaceId: activeStory.workspaceId
+		          }),
+		          discussionBusy: recordDiscussionBusy === "story"
 		        }
 		      ) : null
 		    ] }) }),
@@ -16140,6 +16230,8 @@ window.__ModuleLoader__.load({
 		  onComplete,
 		  onStartFix,
 		  onCancelFix,
+		  onNewDiscussion,
+		  discussionBusy = false,
 		  readOnly = false
 		}) {
 		  return /* @__PURE__ */ (0, import_jsx_runtime10.jsxs)(import_jsx_runtime10.Fragment, { children: [
@@ -16166,27 +16258,42 @@ window.__ModuleLoader__.load({
 		      readOnly ? null : /* @__PURE__ */ (0, import_jsx_runtime10.jsxs)("button", { className: "tf-btn tf-danger", "data-tone": "ghost", type: "button", onClick: onDelete, style: { flex: "0 0 auto" }, children: [
 		        /* @__PURE__ */ (0, import_jsx_runtime10.jsx)(TrashGlyph, {}),
 		        t("delete.action")
-		      ] }),
-		      readOnly || bug.sessionId === void 0 ? null : /* @__PURE__ */ (0, import_jsx_runtime10.jsxs)(
-		        "button",
-		        {
-		          className: "tf-btn",
-		          "data-tone": "live",
-		          type: "button",
-		          onClick: () => onOpenSession(bug.sessionId),
-		          style: { flex: "0 0 auto" },
-		          children: [
-		            /* @__PURE__ */ (0, import_jsx_runtime10.jsx)(ChatGlyph, {}),
-		            t("row.open")
-		          ]
-		        }
-		      )
+		      ] })
 		    ] }),
 		    /* @__PURE__ */ (0, import_jsx_runtime10.jsxs)("div", { className: "tf-grid", children: [
 		      /* @__PURE__ */ (0, import_jsx_runtime10.jsxs)("div", { children: [
 		        /* @__PURE__ */ (0, import_jsx_runtime10.jsxs)("section", { className: "tf-card", children: [
-		          /* @__PURE__ */ (0, import_jsx_runtime10.jsx)(SectionHead, { title: t("detail.bugBody") }),
-		          /* @__PURE__ */ (0, import_jsx_runtime10.jsx)("div", { className: "tf-doc-body", children: bug.bodyMissing ? /* @__PURE__ */ (0, import_jsx_runtime10.jsx)("p", { className: "tf-card-hint", children: t("body.missingGeneric") }) : /* @__PURE__ */ (0, import_jsx_runtime10.jsx)(MarkdownBody, { text: bug.content.join("\n"), t }) })
+		          /* @__PURE__ */ (0, import_jsx_runtime10.jsx)(
+		            SectionHead,
+		            {
+		              title: t("detail.bugBody"),
+		              action: readOnly || onNewDiscussion === void 0 ? void 0 : /* @__PURE__ */ (0, import_jsx_runtime10.jsxs)(
+		                "button",
+		                {
+		                  className: "tf-btn tf-btn-sm",
+		                  "data-tone": "soft",
+		                  type: "button",
+		                  disabled: discussionBusy,
+		                  onClick: onNewDiscussion,
+		                  children: [
+		                    /* @__PURE__ */ (0, import_jsx_runtime10.jsx)(PlusGlyph, {}),
+		                    discussionBusy ? t("detail.discussionStarting") : t("detail.bugDiscussion")
+		                  ]
+		                }
+		              )
+		            }
+		          ),
+		          /* @__PURE__ */ (0, import_jsx_runtime10.jsx)("div", { className: "tf-doc-body", children: bug.bodyMissing ? /* @__PURE__ */ (0, import_jsx_runtime10.jsx)("p", { className: "tf-card-hint", children: t("body.missingGeneric") }) : /* @__PURE__ */ (0, import_jsx_runtime10.jsx)(MarkdownBody, { text: bug.content.join("\n"), t }) }),
+		          /* @__PURE__ */ (0, import_jsx_runtime10.jsx)(
+		            DiscussionSessions,
+		            {
+		              t,
+		              sessions: bug.sessions,
+		              sessionTitle,
+		              onOpenSession,
+		              readOnly
+		            }
+		          )
 		        ] }),
 		        /* @__PURE__ */ (0, import_jsx_runtime10.jsxs)("section", { className: "tf-card", children: [
 		          /* @__PURE__ */ (0, import_jsx_runtime10.jsx)(
@@ -16262,6 +16369,8 @@ window.__ModuleLoader__.load({
 		  onOpenSession,
 		  onOpenPath,
 		  onMissing,
+		  onNewDiscussion,
+		  discussionBusy = false,
 		  readOnly = false
 		}) {
 		  return /* @__PURE__ */ (0, import_jsx_runtime10.jsxs)(import_jsx_runtime10.Fragment, { children: [
@@ -16311,7 +16420,26 @@ window.__ModuleLoader__.load({
 		    /* @__PURE__ */ (0, import_jsx_runtime10.jsxs)("div", { className: "tf-grid", children: [
 		      /* @__PURE__ */ (0, import_jsx_runtime10.jsxs)("div", { children: [
 		        /* @__PURE__ */ (0, import_jsx_runtime10.jsxs)("section", { className: "tf-card", children: [
-		          /* @__PURE__ */ (0, import_jsx_runtime10.jsx)(SectionHead, { title: t("detail.storyBody") }),
+		          /* @__PURE__ */ (0, import_jsx_runtime10.jsx)(
+		            SectionHead,
+		            {
+		              title: t("detail.storyBody"),
+		              action: readOnly || onNewDiscussion === void 0 ? void 0 : /* @__PURE__ */ (0, import_jsx_runtime10.jsxs)(
+		                "button",
+		                {
+		                  className: "tf-btn tf-btn-sm",
+		                  "data-tone": "soft",
+		                  type: "button",
+		                  disabled: discussionBusy,
+		                  onClick: onNewDiscussion,
+		                  children: [
+		                    /* @__PURE__ */ (0, import_jsx_runtime10.jsx)(PlusGlyph, {}),
+		                    discussionBusy ? t("detail.discussionStarting") : t("detail.storyDiscussion")
+		                  ]
+		                }
+		              )
+		            }
+		          ),
 		          /* @__PURE__ */ (0, import_jsx_runtime10.jsx)("div", { className: "tf-doc-body", children: story.bodyMissing ? /* @__PURE__ */ (0, import_jsx_runtime10.jsx)("p", { className: "tf-card-hint", style: { margin: 0 }, children: t("body.missing", { path: story.path }) }) : story.body.trim() === "" ? /* @__PURE__ */ (0, import_jsx_runtime10.jsx)("p", { className: "tf-card-hint", style: { margin: 0 }, children: t("detail.noDescription") }) : /* @__PURE__ */ (0, import_jsx_runtime10.jsx)(
 		            MarkdownBody,
 		            {
@@ -16321,7 +16449,17 @@ window.__ModuleLoader__.load({
 		              onOpenPath,
 		              onMissing
 		            }
-		          ) })
+		          ) }),
+		          /* @__PURE__ */ (0, import_jsx_runtime10.jsx)(
+		            DiscussionSessions,
+		            {
+		              t,
+		              sessions: story.sessions,
+		              sessionTitle,
+		              onOpenSession,
+		              readOnly
+		            }
+		          )
 		        ] }),
 		        /* @__PURE__ */ (0, import_jsx_runtime10.jsxs)("section", { className: "tf-card", children: [
 		          /* @__PURE__ */ (0, import_jsx_runtime10.jsx)(
@@ -17091,6 +17229,9 @@ window.__ModuleLoader__.load({
 		    prepareRequirementSession: async (requirementId, sessionId, kind) => callRemote(
 		      (await ready.promise).prepareRequirementSession(requirementId, sessionId, kind, locale())
 		    ),
+		    prepareDiscussionSession: async (subjectType, subjectId, sessionId, kind) => callRemote(
+		      (await ready.promise).prepareDiscussionSession(subjectType, subjectId, sessionId, kind, locale())
+		    ),
 		    sessionPermissionTier: async (sessionId) => callRemote((await ready.promise).sessionPermissionTier(sessionId, locale())),
 		    previewDelete: async (targets) => callRemote((await ready.promise).previewDelete(targets, locale())),
 		    deleteRecords: async (targets) => callRemote((await ready.promise).deleteRecords(targets, locale())),

package/lib/index.d.ts

@@ -16,6 +16,11 @@ export interface Config {
      * which is the only location this plugin owns.
      */
     dataDir: string;
+    /**
+     * Document root override. Empty uses `<dataDir>/docs`, next to the database;
+     * relative paths resolve against the working directory and `~/` is expanded.
+     */
+    docsDir: string;
     /** SQLite busy timeout in milliseconds; a second instance waits this long for the write lock. */
     busyTimeoutMs: number;
 }
@@ -32,7 +37,8 @@ export declare function apply(ctx: Context, config: Config): void;
 export type { TeamflowDatabase, StartupReport, Role } from './store/db.ts';
 export type { SchemaComment } from './store/schema.ts';
 export { WorkflowStore } from './store/workflow.ts';
-export { DOC_ROOT, docPath, ensureDocTree, resolveDocPath } from './store/docs.ts';
+export { docPath, ensureDocTree, resolveDocPath } from './store/docs.ts';
+export { DOCS_DIRNAME, defaultDocsDir, resolveDocsDir } from './store/paths.ts';
 export type { DocKind as DocFileKind } from './store/docs.ts';
 export type { WorkflowStoreOptions } from './store/workflow.ts';
 export { WorkflowError } from './store/model.ts';

package/lib/index.js

@@ -7,6 +7,9 @@ export const Config = Schema.object({
     dataDir: Schema.string()
         .default('')
         .description('Workbench data directory. Empty uses $DSH_HOME/xirang-ai/dsh-teamflow.'),
+    docsDir: Schema.string()
+        .default('')
+        .description('Document root for requirement, design, story and bug bodies. Empty uses <dataDir>/docs; relative paths and ~/ are supported.'),
     busyTimeoutMs: Schema.number()
         .min(0)
         .max(60_000)
@@ -28,11 +31,13 @@ export function apply(ctx, config) {
         error: (message) => logger.error(message),
     };
     ctx.effect(() => {
-        // Document bodies live in the workspace directory, not the database, so the
-        // panel reads them by `content_path` through the live registry. Without the
-        // registry the store falls back to rows registered by the tool layer.
+        // Document bodies live below the plugin-owned document root, not the
+        // database and not the user's workspace; the panel reads them by
+        // `content_path` relative to that one root. The registry stays wired for
+        // workspace display only.
         const database = openTeamflowDatabase({
             dataDir: config.dataDir,
+            docsDir: config.docsDir,
             busyTimeoutMs: config.busyTimeoutMs,
             // Resolved lazily: the optional registry may register after this effect runs.
             workspaceRoot: (workspaceId) => ctx.get('workspaceRegistry')?.get(workspaceId)?.path,
@@ -66,6 +71,7 @@ export function apply(ctx, config) {
     }, 'teamflow: workbench database');
 }
 export { WorkflowStore } from "./store/workflow.js";
-export { DOC_ROOT, docPath, ensureDocTree, resolveDocPath } from "./store/docs.js";
+export { docPath, ensureDocTree, resolveDocPath } from "./store/docs.js";
+export { DOCS_DIRNAME, defaultDocsDir, resolveDocsDir } from "./store/paths.js";
 export { WorkflowError } from "./store/model.js";
 export { MAX_DELETE_TARGETS } from "./store/workflow.js";