@xirang-ai/dsh-teamflow 0.1.1 → 0.1.2

package/lib/remote/contract.d.ts

@@ -36,7 +36,7 @@ declare module '@deepseek-ai/dsh-typert-protocol' {
         register(contribution: HostContribution): TypertDisposer;
     }
 }
-import type { BugSeverity, BugStatus, DeletePreview, DeleteReport, DeleteTarget, DocKind, RequirementSessionKind, RequirementStatus, RunKind, RunStatus, StorySize, StoryStatus } from '../store/model.ts';
+import type { BugSeverity, BugStatus, DeletePreview, DiscussionSubjectType, DeleteReport, DeleteTarget, DocKind, RequirementSessionKind, RequirementStatus, RunKind, RunStatus, StorySize, StoryStatus } from '../store/model.ts';
 /** npm package that owns these Remote methods. */
 export declare const PACKAGE_NAME = "@xirang-ai/dsh-teamflow";
 /**
@@ -89,6 +89,8 @@ export interface SnapshotStory {
     readonly completedAt: string | null;
     /** Conversation that created the story; null when it was not recorded. */
     readonly createSessionId: string | null;
+    /** Confirmed discussions of this story, newest first. */
+    readonly sessions: readonly SnapshotDiscussionSession[];
 }
 /** One 详细设计 document; its body is fetched on demand by {@link readDoc}. */
 export interface SnapshotDoc {
@@ -121,6 +123,8 @@ export interface SnapshotBug {
     readonly completedAt: string | null;
     /** Conversation that created the defect; null when it was not recorded. */
     readonly createSessionId: string | null;
+    /** Confirmed discussions of this defect, newest first. */
+    readonly sessions: readonly SnapshotDiscussionSession[];
 }
 /** One development or fix run; `sessionId` is the conversation it happened in. */
 export interface SnapshotRun {
@@ -148,6 +152,17 @@ export interface SnapshotRequirementSession {
     readonly linkedAt: string | null;
     readonly createdAt: string;
 }
+/** One discussion conversation attached to a story or a defect. */
+export interface SnapshotDiscussionSession {
+    readonly sessionId: string;
+    /** `discuss` for stories and defects; requirements keep their own kinds. */
+    readonly kind: string;
+    /** Browser preparation time; null only for conversations that skipped it. */
+    readonly preparedAt: string | null;
+    /** Agent confirmation time; null while the discussion is pending. */
+    readonly linkedAt: string | null;
+    readonly createdAt: string;
+}
 /** Everything the list, the design tree and the defect list need in one frame. */
 export interface WorkbenchSnapshot {
     /** When the Host read the rows; the panel shows it next to the refresh button. */
@@ -226,6 +241,16 @@ export interface RequirementSessionReply {
     readonly preparedAt: string | null;
     readonly linkedAt: string | null;
 }
+/** One discussion row as stored; `linkedAt` is null until the Agent confirms. */
+export interface DiscussionSessionReply {
+    readonly subjectType: DiscussionSubjectType;
+    readonly subjectId: string;
+    readonly sessionId: string;
+    readonly kind: string;
+    readonly preparedAt: string | null;
+    readonly linkedAt: string | null;
+    readonly createdAt: string;
+}
 /** Success or failure envelope the browser mounts produce. */
 export type RemoteResult<Value> = {
     readonly ok: true;
@@ -323,6 +348,13 @@ export interface WorkbenchRemote {
      * of the snapshot until `teamflow_link_requirement_session` writes `linkedAt`.
      */
     prepareRequirementSession(requirementId: string, sessionId: string, kind: RequirementSessionKind, locale?: string): Promise<RemoteResult<RequirementSessionReply>>;
+    /**
+     * Register a newly created session as a pending discussion of any subject.
+     *
+     * Same two-phase contract as {@link prepareRequirementSession}, extended to
+     * stories and defects; this method never writes `linkedAt`.
+     */
+    prepareDiscussionSession(subjectType: DiscussionSubjectType, subjectId: string, sessionId: string, kind: string, locale?: string): Promise<RemoteResult<DiscussionSessionReply>>;
     /**
      * Read the tier a conversation was started with, for the session header.
      *
@@ -357,6 +389,7 @@ export declare const METHODS: {
     readonly cancelStory: "cancelStory";
     readonly completeBug: "completeBug";
     readonly prepareRequirementSession: "prepareRequirementSession";
+    readonly prepareDiscussionSession: "prepareDiscussionSession";
     readonly sessionPermissionTier: "sessionPermissionTier";
     readonly previewDelete: "previewDelete";
     readonly deleteRecords: "deleteRecords";

package/lib/remote/contract.js

@@ -22,6 +22,7 @@ export const METHODS = {
     cancelStory: 'cancelStory',
     completeBug: 'completeBug',
     prepareRequirementSession: 'prepareRequirementSession',
+    prepareDiscussionSession: 'prepareDiscussionSession',
     sessionPermissionTier: 'sessionPermissionTier',
     previewDelete: 'previewDelete',
     deleteRecords: 'deleteRecords',
@@ -170,6 +171,21 @@ export const DESCRIPTORS = Object.freeze([
         ]),
         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,

package/lib/remote/service.d.ts

@@ -10,9 +10,9 @@
  */
 import type { Context } from '@deepseek-ai/cordis';
 import { TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
-import type { DeletePreview, DeleteReport, DeleteTarget, RequirementSessionKind } from '../store/model.ts';
+import type { DeletePreview, DeleteReport, DeleteTarget, DiscussionSubjectType, RequirementSessionKind } from '../store/model.ts';
 import type { WorkflowStore } from '../store/workflow.ts';
-import type { AttachmentPolicy, BugRunReply, BugStatusReply, CancelRunReply, DocBody, RequirementSessionReply, RequirementStatusReply, SessionTierReply, StartRunReply, StoryStatusReply, WorkbenchSnapshot } from './contract.ts';
+import type { AttachmentPolicy, BugRunReply, BugStatusReply, CancelRunReply, DiscussionSessionReply, DocBody, RequirementSessionReply, RequirementStatusReply, SessionTierReply, StartRunReply, StoryStatusReply, WorkbenchSnapshot } from './contract.ts';
 /**
  * Remote face of the workbench.
  *
@@ -134,6 +134,19 @@ export declare class WorkbenchService extends TypertRemoteService {
      * @returns the stored pending row.
      */
     prepareRequirementSession(requirementId: string, sessionId: string, kind?: RequirementSessionKind, locale?: string): RequirementSessionReply;
+    /**
+     * Register a newly created conversation as a pending discussion of any subject.
+     *
+     * Same two-phase contract as {@link prepareRequirementSession}: the Agent
+     * confirms with `teamflow_link_session`, and this method never writes the
+     * confirmation time itself.
+     * @param subjectType - requirement, story or bug.
+     * @param subjectId - record the discussion belongs to.
+     * @param sessionId - session created by the browser for this discussion.
+     * @param kind - `discuss` for stories and defects; requirement kinds otherwise.
+     * @returns the stored pending row.
+     */
+    prepareDiscussionSession(subjectType: DiscussionSubjectType, subjectId: string, sessionId: string, kind: string, locale?: string): DiscussionSessionReply;
     /**
      * Compute deletion impact without writing anything.
      * @param targets - records the user selected in the panel.

package/lib/remote/service.js

@@ -12,10 +12,22 @@ import { NAMESPACE, SERVICE_KEY } from "./contract.js";
  * `WorkflowStore.readContent` returns `null` for a missing file, `''` for an
  * empty one, and throws for any other I/O failure.
  */
-function readBody(workflow, workspaceId, path) {
-    const body = workflow.readContent(workspaceId, path);
+function readBody(workflow, path) {
+    const body = workflow.readContent(path);
     return body === null ? { body: '', bodyMissing: true } : { body, bodyMissing: false };
 }
+/** Confirmed discussions of one story or defect, newest first. */
+function discussionsFor(rows, subjectType, subjectId) {
+    return rows
+        .filter((row) => row.subjectType === subjectType && row.subjectId === subjectId)
+        .map((row) => ({
+        sessionId: row.sessionId,
+        kind: row.kind,
+        preparedAt: row.preparedAt,
+        linkedAt: row.linkedAt,
+        createdAt: row.createdAt,
+    }));
+}
 /**
  * Rebuild a failure in the caller's language.
  *
@@ -84,7 +96,7 @@ export class WorkbenchService extends TypertRemoteService {
                     status: requirement.status,
                     updatedAt: requirement.updatedAt,
                     path: requirement.contentPath,
-                    ...readBody(this.workflow, requirement.workspaceId, requirement.contentPath),
+                    ...readBody(this.workflow, requirement.contentPath),
                     completedAt: requirement.completedAt,
                 })),
                 stories: rows.stories.map((story) => ({
@@ -98,10 +110,11 @@ export class WorkbenchService extends TypertRemoteService {
                     createdAt: story.createdAt,
                     updatedAt: story.updatedAt,
                     path: story.contentPath,
-                    ...readBody(this.workflow, story.workspaceId, story.contentPath),
+                    ...readBody(this.workflow, story.contentPath),
                     doneAt: story.doneAt,
                     completedAt: story.completedAt,
                     createSessionId: story.createSessionId,
+                    sessions: discussionsFor(rows.discussionSessions, 'story', story.id),
                 })),
                 docs: rows.docs.map((doc) => ({
                     id: doc.id,
@@ -122,10 +135,11 @@ export class WorkbenchService extends TypertRemoteService {
                     status: bug.status,
                     resolution: bug.resolution,
                     updatedAt: bug.updatedAt,
-                    ...readBody(this.workflow, bug.workspaceId, bug.contentPath),
+                    ...readBody(this.workflow, bug.contentPath),
                     fixedAt: bug.fixedAt,
                     completedAt: bug.completedAt,
                     createSessionId: bug.createSessionId,
+                    sessions: discussionsFor(rows.discussionSessions, 'bug', bug.id),
                 })),
                 runs: rows.runs.map((run) => ({
                     id: run.id,
@@ -400,6 +414,35 @@ export class WorkbenchService extends TypertRemoteService {
             throw localizedFailure(error, locale);
         }
     }
+    /**
+     * Register a newly created conversation as a pending discussion of any subject.
+     *
+     * Same two-phase contract as {@link prepareRequirementSession}: the Agent
+     * confirms with `teamflow_link_session`, and this method never writes the
+     * confirmation time itself.
+     * @param subjectType - requirement, story or bug.
+     * @param subjectId - record the discussion belongs to.
+     * @param sessionId - session created by the browser for this discussion.
+     * @param kind - `discuss` for stories and defects; requirement kinds otherwise.
+     * @returns the stored pending row.
+     */
+    prepareDiscussionSession(subjectType, subjectId, sessionId, kind, locale) {
+        try {
+            const row = this.workflow.prepareDiscussionSession(subjectType, subjectId, sessionId, kind);
+            return {
+                subjectType: row.subjectType,
+                subjectId: row.subjectId,
+                sessionId: row.sessionId,
+                kind: row.kind,
+                preparedAt: row.preparedAt,
+                linkedAt: row.linkedAt,
+                createdAt: row.createdAt,
+            };
+        }
+        catch (error) {
+            throw localizedFailure(error, locale);
+        }
+    }
     /**
      * Compute deletion impact without writing anything.
      * @param targets - records the user selected in the panel.
@@ -459,7 +502,7 @@ export class WorkbenchService extends TypertRemoteService {
             return {
                 id: doc.id,
                 title: doc.title,
-                ...readBody(this.workflow, requirement.workspaceId, doc.contentPath),
+                ...readBody(this.workflow, doc.contentPath),
             };
         }
         catch (error) {

package/lib/requirement-discussion.d.ts

@@ -42,3 +42,26 @@ export declare function presetForRequirementDiscussion(kind: RequirementDiscussi
  * @returns the first message of the discussion, carrying the supplement slot.
  */
 export declare function buildRequirementDiscussionPrompt(kind?: RequirementDiscussionKind): string;
+/** Preset for a story discussion (reuses the standalone story agent). */
+export declare const STORY_DISCUSSION_PRESET = "xirang-story";
+/** Preset for a defect discussion. */
+export declare const BUG_DISCUSSION_PRESET = "xirang-bug";
+/** A record kind whose detail page can start a discussion. */
+export type RecordDiscussionKind = 'story' | 'bug';
+/**
+ * Pick the preset a story or defect discussion runs under.
+ * @param kind - `story` or `bug`.
+ * @returns the preset id declared in `cordis.patch.yml`.
+ */
+export declare function presetForRecordDiscussion(kind: RecordDiscussionKind): string;
+/**
+ * Build the prompt sent when the user starts a discussion from a story or defect page.
+ *
+ * The title travels in the prompt because it is what the reader recognises;
+ * the id stays out of it, just like requirement discussions: the tools resolve
+ * the record through the session binding.
+ * @param kind - `story` or `bug`.
+ * @param title - story or defect title shown to the reader.
+ * @returns the first message of the discussion, carrying the supplement slot.
+ */
+export declare function buildRecordDiscussionPrompt(kind: RecordDiscussionKind, title: string): string;

package/lib/requirement-discussion.js

@@ -58,3 +58,29 @@ export function buildRequirementDiscussionPrompt(kind = 'design') {
     }
     return ['【继续讨论需求与概要设计】', '', '我的补充：'].join('\n');
 }
+/** Preset for a story discussion (reuses the standalone story agent). */
+export const STORY_DISCUSSION_PRESET = 'xirang-story';
+/** Preset for a defect discussion. */
+export const BUG_DISCUSSION_PRESET = 'xirang-bug';
+/**
+ * Pick the preset a story or defect discussion runs under.
+ * @param kind - `story` or `bug`.
+ * @returns the preset id declared in `cordis.patch.yml`.
+ */
+export function presetForRecordDiscussion(kind) {
+    return kind === 'bug' ? BUG_DISCUSSION_PRESET : STORY_DISCUSSION_PRESET;
+}
+/**
+ * Build the prompt sent when the user starts a discussion from a story or defect page.
+ *
+ * The title travels in the prompt because it is what the reader recognises;
+ * the id stays out of it, just like requirement discussions: the tools resolve
+ * the record through the session binding.
+ * @param kind - `story` or `bug`.
+ * @param title - story or defect title shown to the reader.
+ * @returns the first message of the discussion, carrying the supplement slot.
+ */
+export function buildRecordDiscussionPrompt(kind, title) {
+    const heading = kind === 'bug' ? '【继续讨论缺陷】' : '【继续讨论故事】';
+    return [heading, title, '', '我的补充：'].join('\n');
+}

package/lib/store/db.d.ts

@@ -43,6 +43,10 @@ export interface StartupReport {
     readonly file: string;
     /** Database file rendered for logs (`$DSH_HOME/...`). */
     readonly displayFile: string;
+    /** Absolute document root that holds `requirements/`, `stories/` and `bugs/`. */
+    readonly docsDir: string;
+    /** Document root rendered for logs (`$DSH_HOME/...`). */
+    readonly displayDocsDir: string;
     /** Version stored before this start, `null` on the first start. */
     readonly fromVersion: string | null;
     /** Version now running. */
@@ -89,10 +93,11 @@ export interface OpenDatabaseOptions {
     /** `Config.dataDir` override; empty uses the plugin home below `$DSH_HOME`. */
     readonly dataDir?: string;
     /**
-     * Where documents are written when a workspace directory is unknown yet.
-     * Production passes the workspace path via `registerWorkspace` instead.
+     * `Config.docsDir` override for the document root; empty uses `<dataDir>/docs`.
+     * Relative paths and `~/` resolve like {@link resolveDataDir}; an invalid value
+     * throws instead of falling back to the default.
      */
-    readonly docsRoot?: string;
+    readonly docsDir?: string;
     /** Resolver consulted before the registry, for the Host's live workspace list. */
     readonly workspaceRoot?: (workspaceId: string) => string | undefined;
     /** SQLite busy timeout in milliseconds. */

package/lib/store/db.js

@@ -11,7 +11,7 @@
 import { DatabaseSync } from 'node:sqlite';
 import { contextualError, describeError } from "../errors.js";
 import { readPluginVersion } from "../version.js";
-import { DATABASE_FILENAME, databaseFile, ensureDataDir, resolveDataDir, toDisplayPath, } from "./paths.js";
+import { DATABASE_FILENAME, databaseFile, ensureDataDir, ensureDocsDir, resolveDataDir, resolveDocsDir, toDisplayPath, } from "./paths.js";
 import { BUILTIN_ROLES, MIGRATIONS, TARGET_SCHEMA_VERSION, syncSchemaComments, } from "./schema.js";
 import { withTransaction } from "./transaction.js";
 import { runUpgrades } from "./upgrades.js";
@@ -36,6 +36,31 @@ export const META_KEYS = {
     /** Schema version, mirrored from `PRAGMA user_version` for inspection. */
     schemaVersion: 'schema_version',
 };
+/** Prefix of legacy content paths, which were relative to a workspace root. */
+const LEGACY_DOC_PREFIX = '.xirang-ai/dsh-teamflow/';
+/**
+ * Rewrite legacy workspace-relative `content_path` values onto the document
+ * root. Idempotent: rows already on the new basis do not match the prefix, so
+ * a restart after a partial failure simply finishes the job.
+ *
+ * This is a data-basis normalization, not a schema migration: the table layout
+ * and `user_version` stay untouched.
+ *
+ * @returns how many rows were rewritten.
+ */
+function normalizeContentPaths(db) {
+    const tables = ['requirements', 'design_docs', 'stories', 'bugs'];
+    return withTransaction(db, () => {
+        let changed = 0;
+        for (const table of tables) {
+            const result = db
+                .prepare(`UPDATE ${table} SET content_path = substr(content_path, ?) WHERE content_path LIKE ?`)
+                .run(LEGACY_DOC_PREFIX.length + 1, `${LEGACY_DOC_PREFIX}%`);
+            changed += Number(result.changes);
+        }
+        return changed;
+    });
+}
 function configure(db, busyTimeoutMs) {
     const timeout = Number.isFinite(busyTimeoutMs) ? Math.max(0, Math.trunc(busyTimeoutMs)) : 0;
     // WAL keeps readers unblocked while a writer holds the lock; NORMAL is the
@@ -175,6 +200,7 @@ export function openTeamflowDatabase(options = {}) {
     const log = options.log ?? SILENT_LOGGER;
     const version = options.version ?? readPluginVersion();
     const dataDir = resolveDataDir(options.dataDir);
+    const docsDir = ensureDocsDir(resolveDocsDir(options.docsDir, dataDir));
     const file = databaseFile(dataDir);
     try {
         ensureDataDir(dataDir);
@@ -194,10 +220,16 @@ export function openTeamflowDatabase(options = {}) {
         const appliedMigrations = migrate(db, log);
         syncSchemaComments(db);
         seedBuiltinRoles(db);
+        const normalizedPaths = normalizeContentPaths(db);
+        if (normalizedPaths > 0) {
+            log.info(`normalized ${normalizedPaths} document path(s) onto the document root ${toDisplayPath(docsDir)}`);
+        }
         const reconciliation = reconcileVersion(db, version, log);
         const report = {
             file,
             displayFile: toDisplayPath(file),
+            docsDir,
+            displayDocsDir: toDisplayPath(docsDir),
             fromVersion: reconciliation.fromVersion,
             toVersion: version,
             outcome: reconciliation.outcome,
@@ -225,7 +257,7 @@ export function openTeamflowDatabase(options = {}) {
             db,
             report,
             workflow: new WorkflowStore(db, {
-                docsRoot: options.docsRoot,
+                docsRoot: docsDir,
                 workspaceRoot: options.workspaceRoot,
                 warn: (message) => log.warn(message),
             }),

package/lib/store/docs.d.ts

@@ -1,9 +1,7 @@
-/** 文档根目录名，工作区内的隐藏目录。 */
-export declare const DOC_ROOT = ".xirang-ai/dsh-teamflow";
 /** 文档种类：决定落盘路径。 */
 export type DocKind = 'requirement' | 'designDoc' | 'story' | 'bug';
 /**
- * 计算一份文档在工作区内的相对路径。
+ * 计算一份文档在文档根内的相对路径。
  *
  * @param kind - 文档种类
  * @param ids - 该种类需要的标识（designDoc 需要需求 id 与文档 id）
@@ -14,19 +12,19 @@ export declare function docPath(kind: DocKind, ids: {
     requirementId?: string;
 }): string;
 /**
- * 把相对路径拼到工作区根上；只接受插件自己生成的、以 `/` 分隔的工作区相对路径。
+ * 把相对路径拼到文档根上；只接受插件自己生成的、以 `/` 分隔的文档相对路径。
  *
  * 拒绝 POSIX 绝对路径、Windows 盘符/UNC/反斜杠路径与任何 `..`，最后再做一次
  * 词法 containment 校验，确保结果仍落在 `root` 之内。
  */
 export declare function resolveDocPath(root: string, relative: string): string;
-/** 工作区路径 + 相对路径的展示形式（日志与工具结果用，始终 `/`）。 */
+/** 文档相对路径的展示形式（日志与工具结果用，始终 `/`）。 */
 export declare function displayPath(relative: string): string;
 /**
- * 首次为一个工作区准备文档目录：建目录、写 `.gitignore`、必要时把 `.xirang-ai/`
- * 追加进工作区自己的 `.gitignore`。
+ * 首次为文档根准备共享目录：只建 `requirements/`、`stories/`、`bugs/`，
+ * 不碰工作区，也不写 `.gitignore`。
  *
- * @param root - 工作区根目录（绝对路径）
+ * @param root - 文档根目录（绝对路径）
  * @returns 实际创建的目录（相对路径），便于工具结果里说明
  */
 export declare function ensureDocTree(root: string): string[];
@@ -46,7 +44,7 @@ export declare function writeDoc(root: string, relative: string, body: string):
 export declare function removeDoc(root: string, relative: string): void;
 /** 已挪出正式路径、等待随数据库事务一起确认删除的文档。 */
 export interface StagedDoc {
-    /** 原来的工作区相对路径；事务失败时据此还原。 */
+    /** 原来的文档相对路径；事务失败时据此还原。 */
     readonly relative: string;
     /** 临时绝对路径，与正式文件同目录，保证 rename 是原子的。 */
     readonly staged: string;
@@ -58,8 +56,8 @@ export interface StagedDoc {
  * 到临时名，再在 SQLite 事务里删记录：事务失败就把文件改回来，事务成功才真正
  * `unlink`。这样任何时刻都不会出现「记录已经没了、正式路径上的文件还在」的悬挂态。
  *
- * @param root - 工作区根目录
- * @param relative - 文档的工作区相对路径
+ * @param root - 文档根目录
+ * @param relative - 文档相对路径
  * @returns 暂存信息；文件本来就不存在时返回 `null`
  */
 export declare function stageDocDeletion(root: string, relative: string): StagedDoc | null;

package/lib/store/docs.js

@@ -1,23 +1,20 @@
 /**
- * 文档落盘：正文不进 SQLite，只记工作区内的相对路径。
+ * 文档落盘：正文不进 SQLite，只记文档根内的相对路径。
  *
- * 目录结构（相对工作区根）：
+ * 目录结构（相对文档根，默认 `$DSH_HOME/xirang-ai/dsh-teamflow/docs`）：
  *
- *   .xirang-ai/dsh-teamflow/
- *     requirements/<req_id>/requirement.md 需求 + 概要设计正文
- *     requirements/<req_id>/docs/<doc_id>.md 详细设计文档（一份需求可以有很多份）
- *     stories/<sty_id>/story.md            故事说明 + 验收标准
- *     bugs/<bug_id>/bug.md                 缺陷正文（描述、复现、期望、实际、环境）
+ *   requirements/<req_id>/requirement.md 需求 + 概要设计正文
+ *   requirements/<req_id>/docs/<doc_id>.md 详细设计文档（一份需求可以有很多份）
+ *   stories/<sty_id>/story.md            故事说明 + 验收标准
+ *   bugs/<bug_id>/bug.md                 缺陷正文（描述、复现、期望、实际、环境）
  *
  * 所有写操作走「临时文件 + rename」，避免中途崩溃留下半截文档。
  */
 import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmdirSync, rmSync, writeFileSync, } from 'node:fs';
-import { dirname, isAbsolute, join, posix, resolve, sep, win32 } from 'node:path';
+import { dirname, isAbsolute, posix, resolve, sep, win32 } from 'node:path';
 import { describeError } from "../errors.js";
-/** 文档根目录名，工作区内的隐藏目录。 */
-export const DOC_ROOT = '.xirang-ai/dsh-teamflow';
 /**
- * 计算一份文档在工作区内的相对路径。
+ * 计算一份文档在文档根内的相对路径。
  *
  * @param kind - 文档种类
  * @param ids - 该种类需要的标识（designDoc 需要需求 id 与文档 id）
@@ -27,17 +24,17 @@ export function docPath(kind, ids) {
     const id = requireId(ids.id);
     switch (kind) {
         case 'requirement':
-            return `${DOC_ROOT}/requirements/${id}/requirement.md`;
+            return `requirements/${id}/requirement.md`;
         case 'story':
-            return `${DOC_ROOT}/stories/${id}/story.md`;
+            return `stories/${id}/story.md`;
         case 'bug':
-            return `${DOC_ROOT}/bugs/${id}/bug.md`;
+            return `bugs/${id}/bug.md`;
         case 'designDoc':
-            return `${DOC_ROOT}/requirements/${requireId(ids.requirementId)}/docs/${id}.md`;
+            return `requirements/${requireId(ids.requirementId)}/docs/${id}.md`;
     }
 }
 /**
- * 把相对路径拼到工作区根上；只接受插件自己生成的、以 `/` 分隔的工作区相对路径。
+ * 把相对路径拼到文档根上；只接受插件自己生成的、以 `/` 分隔的文档相对路径。
  *
  * 拒绝 POSIX 绝对路径、Windows 盘符/UNC/反斜杠路径与任何 `..`，最后再做一次
  * 词法 containment 校验，确保结果仍落在 `root` 之内。
@@ -46,10 +43,10 @@ export function resolveDocPath(root, relative) {
     if (relative.length === 0)
         throw new Error('teamflow: document path is empty');
     if (relative.includes('\0') || relative.includes('\\')) {
-        throw new Error(`teamflow: document path must be workspace-relative, got "${relative}"`);
+        throw new Error(`teamflow: document path must be relative to the document root, got "${relative}"`);
     }
     if (isAbsolute(relative) || win32.isAbsolute(relative) || /^[A-Za-z]:/.test(relative)) {
-        throw new Error(`teamflow: document path must be workspace-relative, got "${relative}"`);
+        throw new Error(`teamflow: document path must be relative to the document root, got "${relative}"`);
     }
     const segments = relative.split('/');
     if (segments.some((part) => part === '..' || part === '.' || part.length === 0)) {
@@ -58,27 +55,23 @@ export function resolveDocPath(root, relative) {
     const base = resolve(root);
     const absolute = resolve(base, ...segments);
     if (absolute !== base && !absolute.startsWith(`${base}${sep}`)) {
-        throw new Error(`teamflow: document path escapes the workspace, got "${relative}"`);
+        throw new Error(`teamflow: document path escapes the document root, got "${relative}"`);
     }
     return absolute;
 }
-/** 工作区路径 + 相对路径的展示形式（日志与工具结果用，始终 `/`）。 */
+/** 文档相对路径的展示形式（日志与工具结果用，始终 `/`）。 */
 export function displayPath(relative) {
     return relative.split(sep).join(posix.sep);
 }
 /**
- * 首次为一个工作区准备文档目录：建目录、写 `.gitignore`、必要时把 `.xirang-ai/`
- * 追加进工作区自己的 `.gitignore`。
+ * 首次为文档根准备共享目录：只建 `requirements/`、`stories/`、`bugs/`，
+ * 不碰工作区，也不写 `.gitignore`。
  *
- * @param root - 工作区根目录（绝对路径）
+ * @param root - 文档根目录（绝对路径）
  * @returns 实际创建的目录（相对路径），便于工具结果里说明
  */
 export function ensureDocTree(root) {
-    const dirs = [
-        `${DOC_ROOT}/requirements`,
-        `${DOC_ROOT}/stories`,
-        `${DOC_ROOT}/bugs`,
-    ];
+    const dirs = ['requirements', 'stories', 'bugs'];
     const created = [];
     for (const dir of dirs) {
         const absolute = resolveDocPath(root, dir);
@@ -87,11 +80,6 @@ export function ensureDocTree(root) {
             created.push(dir);
         }
     }
-    const localIgnore = resolveDocPath(root, `${DOC_ROOT}/.gitignore`);
-    if (!existsSync(localIgnore)) {
-        writeFileSync(localIgnore, '*\n', 'utf8');
-    }
-    appendWorkspaceGitignore(root);
     return created;
 }
 /**
@@ -144,8 +132,8 @@ let stagedSequence = 0;
  * 到临时名，再在 SQLite 事务里删记录：事务失败就把文件改回来，事务成功才真正
  * `unlink`。这样任何时刻都不会出现「记录已经没了、正式路径上的文件还在」的悬挂态。
  *
- * @param root - 工作区根目录
- * @param relative - 文档的工作区相对路径
+ * @param root - 文档根目录
+ * @param relative - 文档相对路径
  * @returns 暂存信息；文件本来就不存在时返回 `null`
  */
 export function stageDocDeletion(root, relative) {
@@ -182,10 +170,10 @@ export function dropStagedDoc(staged) {
  * 只删空目录：目录里还有别的东西时立刻停下，避免误删用户手工放进来的文件。
  */
 export function pruneEmptyDirectories(root, relative) {
-    const boundary = resolveDocPath(root, DOC_ROOT);
+    const boundary = resolve(root);
     let directory = dirname(resolveDocPath(root, relative));
     // Stop before the shared `requirements/`, `stories/`, `bugs/` roots: those
-    // belong to the workspace tree, not to the record being deleted.
+    // belong to the document tree, not to the record being deleted.
     while (directory !== boundary && dirname(directory) !== boundary && directory.startsWith(`${boundary}${sep}`)) {
         try {
             if (readdirSync(directory).length > 0)
@@ -211,18 +199,3 @@ function requireId(id) {
     }
     return id;
 }
-/** 把 `.xirang-ai/` 追加到工作区 `.gitignore`；没有该文件就创建一个只含这一行的。 */
-function appendWorkspaceGitignore(root) {
-    const ignore = join(root, '.gitignore');
-    const entry = '.xirang-ai/';
-    if (!existsSync(ignore)) {
-        writeFileSync(ignore, `${entry}\n`, 'utf8');
-        return;
-    }
-    const current = readFileSync(ignore, 'utf8');
-    const lines = current.split('\n').map((line) => line.trim());
-    if (lines.includes(entry) || lines.includes('.xirang-ai'))
-        return;
-    const suffix = current.endsWith('\n') || current.length === 0 ? '' : '\n';
-    writeFileSync(ignore, `${current}${suffix}${entry}\n`, 'utf8');
-}

package/lib/store/model.d.ts

@@ -198,6 +198,27 @@ export interface RequirementSession {
     readonly linkedAt: string | null;
     readonly createdAt: string;
 }
+/** Which kind of record a discussion conversation belongs to. */
+export declare const DISCUSSION_SUBJECT_TYPES: readonly ["requirement", "story", "bug"];
+export type DiscussionSubjectType = (typeof DISCUSSION_SUBJECT_TYPES)[number];
+/** Discussion kind used by stories and defects; requirements keep their own kinds. */
+export declare const GENERAL_DISCUSSION_KIND = "discuss";
+/**
+ * One conversation registered against a requirement, story or defect.
+ *
+ * Rows start unconfirmed (`linkedAt` null) when the browser prepares a
+ * discussion and become visible once the Agent confirms with `linkedAt`.
+ */
+export interface DiscussionSession {
+    readonly subjectType: DiscussionSubjectType;
+    readonly subjectId: string;
+    readonly sessionId: string;
+    /** `create` / `design` / `detail` / `split` for requirements, `discuss` otherwise. */
+    readonly kind: string;
+    readonly preparedAt: string | null;
+    readonly linkedAt: string | null;
+    readonly createdAt: string;
+}
 /**
  * One consistent read of every table the workbench renders.
  *
@@ -214,6 +235,8 @@ export interface BoardRows {
     readonly docStories: readonly DocStoryLink[];
     /** Requirement conversations, newest first; design rows may still be unconfirmed. */
     readonly requirementSessions: readonly RequirementSession[];
+    /** Confirmed story and defect discussions, newest first. */
+    readonly discussionSessions: readonly DiscussionSession[];
 }
 /** Input for {@link WorkflowStore.createDesignDoc}. */
 export interface CreateDesignDocInput {