@xirang-ai/dsh-teamflow 0.1.1 → 0.1.2

package/lib/store/workflow.js

@@ -1,5 +1,5 @@
 import { isPermissionTier } from "../permission-tier.js";
-import { docPath, dropStagedDoc, ensureDocTree, pruneEmptyDirectories, readDoc, restoreStagedDoc, stageDocDeletion, writeDoc, } from "./docs.js";
+import { docPath, dropStagedDoc, pruneEmptyDirectories, readDoc, restoreStagedDoc, stageDocDeletion, writeDoc, } from "./docs.js";
 import { newId } from "./ids.js";
 import { BUG_SEVERITIES, BUG_STATUSES, DELETABLE_KINDS, DOC_KINDS, REQUIREMENT_STATUSES, RUN_STATUSES, STORY_SIZES, STORY_STATUSES, WorkflowError, } from "./model.js";
 import { describeError } from "../errors.js";
@@ -69,9 +69,20 @@ function toDesignDoc(row) {
         updatedAt: text(row, 'updated_at'),
     };
 }
+function toDiscussionSession(row) {
+    return {
+        subjectType: text(row, 'subject_type'),
+        subjectId: text(row, 'subject_id'),
+        sessionId: text(row, 'session_id'),
+        kind: text(row, 'kind'),
+        preparedAt: nullableText(row, 'prepared_at'),
+        linkedAt: nullableText(row, 'linked_at'),
+        createdAt: text(row, 'created_at'),
+    };
+}
 function toRequirementSession(row) {
     return {
-        requirementId: text(row, 'requirement_id'),
+        requirementId: text(row, 'subject_id'),
         sessionId: text(row, 'session_id'),
         kind: text(row, 'kind'),
         preparedAt: nullableText(row, 'prepared_at'),
@@ -195,68 +206,55 @@ export class WorkflowStore {
     #docsRoot;
     #workspaceRoot;
     #warn;
-    constructor(db, options = {}) {
+    constructor(db, options) {
         this.#db = db;
         this.#now = options.now ?? (() => new Date().toISOString());
-        this.#docsRoot = options.docsRoot ?? '';
+        this.#docsRoot = options.docsRoot;
         this.#workspaceRoot = options.workspaceRoot ?? (() => undefined);
         this.#warn = options.warn ?? (() => { });
     }
     /**
-     * Remember where a workspace lives on disk. Documents are written into that
-     * directory, so this must be called before the first file-backed write;
-     * repeated calls with the same path are no-ops.
+     * Remember where a workspace lives on disk. Document bodies no longer live
+     * there, but the path is still recorded for display and for future
+     * workspace-scoped features; repeated calls with the same path are no-ops.
      */
     registerWorkspace(workspaceId, path) {
         const id = requiredText(workspaceId, 'workspaceId');
         const root = requiredText(path, 'path');
-        ensureDocTree(root);
         const now = this.#now();
         this.#db
             .prepare(`INSERT INTO workspaces (workspace_id, path, created_at, updated_at) VALUES (?, ?, ?, ?)
          ON CONFLICT(workspace_id) DO UPDATE SET path = excluded.path, updated_at = excluded.updated_at`)
             .run(id, root, now, now);
     }
-    /** Directory a workspace's documents live in, or null when unknown. */
+    /** Directory a registered workspace lives in, or null when unknown. */
     workspacePath(workspaceId) {
         const row = this.#db.prepare('SELECT path FROM workspaces WHERE workspace_id = ?').get(workspaceId);
         if (row !== undefined)
             return text(row, 'path');
-        return this.#workspaceRoot(workspaceId) ?? (this.#docsRoot.length === 0 ? null : this.#docsRoot);
+        return this.#workspaceRoot(workspaceId) ?? null;
     }
     /**
-     * Read a document body by its workspace-relative path.
+     * Read a document body by its document-root-relative path.
      *
      * `null` means the file does not exist; `''` means it exists and is empty.
-     * A workspace without a directory is a configuration error, not a missing
-     * document, so it is reported as `file_error` instead of being folded into
-     * either empty result.
+     * Every record resolves against the one configured document root, so a
+     * legacy path simply misses instead of falling back to a workspace.
      */
-    readContent(workspaceId, relativePath) {
-        const root = this.workspacePath(workspaceId);
-        if (root === null) {
-            throw new WorkflowError('file_error', `workspace ${workspaceId} has no directory yet; call registerWorkspace first`);
-        }
-        return readDoc(root, relativePath);
+    readContent(relativePath) {
+        return readDoc(this.#docsRoot, relativePath);
     }
     /** Rewrite a document body; the path comes from the row, so it is always current. */
-    writeContent(workspaceId, relativePath, body) {
-        writeDoc(this.#root(workspaceId), relativePath, body);
-    }
-    #root(workspaceId) {
-        const root = this.workspacePath(workspaceId);
-        if (root === null) {
-            throw new WorkflowError('invalid_input', `workspace ${workspaceId} has no directory yet; call registerWorkspace first`);
-        }
-        return root;
+    writeContent(relativePath, body) {
+        writeDoc(this.#docsRoot, relativePath, body);
     }
     /**
      * Write one entity's body to its canonical path and return that path.
      * Empty bodies still create the file so the address in the database resolves.
      */
-    #persistDoc(kind, workspaceId, ids, body) {
+    #persistDoc(kind, ids, body) {
         const relative = docPath(kind, ids);
-        writeDoc(this.#root(workspaceId), relative, body);
+        writeDoc(this.#docsRoot, relative, body);
         return relative;
     }
     // ---------------------------------------------------------------- queries
@@ -284,47 +282,121 @@ export class WorkflowStore {
     /**
      * Register a browser-created session as a pending discussion for a requirement.
      *
+     * Kept as a thin wrapper over {@link prepareDiscussionSession} so the
+     * requirement page and its tests keep their existing shape.
+     */
+    prepareRequirementSession(requirementId, sessionId, kind = 'design') {
+        const session = this.prepareDiscussionSession('requirement', requirementId, sessionId, kind);
+        return {
+            requirementId: session.subjectId,
+            sessionId: session.sessionId,
+            kind: session.kind,
+            preparedAt: session.preparedAt,
+            linkedAt: session.linkedAt,
+            createdAt: session.createdAt,
+        };
+    }
+    /**
+     * Register a browser-created session as a pending discussion for a subject.
+     *
      * The browser creates the session first, then calls this before the user can
      * send the first message. The row stays invisible in `listBoard` until the
-     * Agent confirms it through {@link linkRequirementSession}.
+     * Agent confirms it through `teamflow_link_session`; this method never writes
+     * `linked_at`, so the client cannot skip Agent confirmation.
      */
-    prepareRequirementSession(requirementId, sessionId, kind = 'design') {
+    prepareDiscussionSession(subjectType, subjectId, sessionId, kind) {
+        if (subjectType !== 'requirement' && subjectType !== 'story' && subjectType !== 'bug') {
+            throw new WorkflowError('invalid_input', `prepareDiscussionSession 参数非法：subjectType=${String(subjectType)}，期望 requirement|story|bug`);
+        }
+        const subject = (subjectId ?? '').trim();
+        if (subject.length === 0) {
+            throw new WorkflowError('invalid_input', 'prepareDiscussionSession 参数非法：subjectId 为空');
+        }
+        const session = (sessionId ?? '').trim();
+        if (session.length === 0) {
+            throw new WorkflowError('invalid_input', 'prepareDiscussionSession 参数非法：sessionId 为空');
+        }
+        const discussionKind = (kind ?? '').trim();
+        if (discussionKind.length === 0) {
+            throw new WorkflowError('invalid_input', 'prepareDiscussionSession 参数非法：kind 为空');
+        }
+        if (subjectType === 'requirement' &&
+            discussionKind !== 'design' &&
+            discussionKind !== 'detail' &&
+            discussionKind !== 'split') {
+            throw new WorkflowError('invalid_input', `kind must be design, detail or split, got ${String(kind)}`);
+        }
         return withTransaction(this.#db, () => {
-            const requirement = this.#requireRequirement(requirementId);
-            const session = requiredText(sessionId, 'sessionId');
-            if (kind !== 'design' && kind !== 'detail' && kind !== 'split') {
-                throw new WorkflowError('invalid_input', `kind must be design, detail or split, got ${String(kind)}`);
+            this.#requireSubject(subjectType, subject);
+            const rows = this.#db
+                .prepare('SELECT * FROM discussion_sessions WHERE session_id = ?')
+                .all(session);
+            if (rows.length > 1) {
+                throw new WorkflowError('invalid_input', `session ${session} is already bound to ${rows.length} discussions`);
             }
-            const existing = this.#db
-                .prepare('SELECT * FROM requirement_sessions WHERE session_id = ?')
-                .get(session);
+            const existing = rows[0];
             if (existing !== undefined) {
-                const row = toRequirementSession(existing);
-                if (row.requirementId !== requirement.id) {
-                    throw new WorkflowError('invalid_input', `session ${session} already belongs to requirement ${row.requirementId}`);
+                const row = toDiscussionSession(existing);
+                if (row.subjectType !== subjectType || row.subjectId !== subject) {
+                    throw new WorkflowError('invalid_input', `session ${session} already belongs to ${row.subjectType} ${row.subjectId}`);
                 }
                 if (row.kind === 'create') {
                     throw new WorkflowError('invalid_input', `session ${session} created its requirement, so it cannot also be a discussion`);
                 }
-                if (row.kind !== kind) {
+                if (row.kind !== discussionKind) {
                     throw new WorkflowError('invalid_input', `session ${session} is already prepared as a ${row.kind} discussion`);
                 }
+                // Repeated prepares keep the original timestamp; only the first write
+                // records when the browser started the conversation.
                 return row;
             }
             const now = this.#now();
             this.#db
-                .prepare(`INSERT INTO requirement_sessions
-             (requirement_id, session_id, kind, prepared_at, linked_at, created_at)
-           VALUES (?, ?, ?, ?, NULL, ?)`)
-                .run(requirement.id, session, kind, now, now);
-            return this.#requireRequirementSession(session);
+                .prepare(`INSERT INTO discussion_sessions
+             (subject_type, subject_id, session_id, kind, prepared_at, linked_at, created_at)
+           VALUES (?, ?, ?, ?, ?, NULL, ?)
+           ON CONFLICT (subject_type, subject_id, session_id)
+           DO UPDATE SET prepared_at = excluded.prepared_at`)
+                .run(subjectType, subject, session, discussionKind, now, now);
+            return this.#requireDiscussionSession(session, subjectType, subject);
+        });
+    }
+    /**
+     * Confirm the current session as the discussion it was prepared for.
+     *
+     * Called by `teamflow_link_session`; repeated calls are idempotent so a model
+     * retry cannot rewrite the confirmation time.
+     */
+    linkDiscussionSession(sessionId) {
+        return withTransaction(this.#db, () => {
+            const session = requiredText(sessionId, 'sessionId');
+            const rows = this.#db
+                .prepare('SELECT * FROM discussion_sessions WHERE session_id = ?')
+                .all(session);
+            if (rows.length === 0) {
+                throw new WorkflowError('not_found', `teamflow_link_session 未能登记：当前会话 ${session} 没有与任何需求、故事或缺陷绑定`);
+            }
+            if (rows.length > 1) {
+                throw new WorkflowError('invalid_input', `teamflow_link_session 未能登记：数据异常：当前会话 ${session} 绑定到 ${rows.length} 个对象`);
+            }
+            const current = toDiscussionSession(rows[0]);
+            if (current.kind === 'create') {
+                throw new WorkflowError('invalid_input', `session ${session} created a requirement and is not a discussion`);
+            }
+            if (current.linkedAt !== null)
+                return current;
+            this.#db
+                .prepare(`UPDATE discussion_sessions SET linked_at = ?
+            WHERE subject_type = ? AND subject_id = ? AND session_id = ?`)
+                .run(this.#now(), current.subjectType, current.subjectId, session);
+            return this.#requireDiscussionSession(session, current.subjectType, current.subjectId);
         });
     }
     /**
-     * Confirm the current session as a discussion of the requirement prepared for it.
+     * Confirm the current session as a requirement discussion.
      *
-     * Called by `teamflow_link_requirement_session`; repeated calls are idempotent
-     * so a model retry cannot create duplicate history rows.
+     * Kept for `teamflow_link_requirement_session`; new callers use
+     * {@link linkDiscussionSession}.
      */
     linkRequirementSession(sessionId) {
         return withTransaction(this.#db, () => {
@@ -336,36 +408,64 @@ export class WorkflowStore {
             if (current.linkedAt !== null)
                 return current;
             this.#db
-                .prepare("UPDATE requirement_sessions SET linked_at = ? WHERE session_id = ? AND kind IN ('design','detail','split')")
+                .prepare("UPDATE discussion_sessions SET linked_at = ? WHERE subject_type = 'requirement' AND session_id = ? AND kind IN ('design','detail','split')")
                 .run(this.#now(), session);
             return this.#requireRequirementSession(session);
         });
     }
-    /** Pending or linked conversation prepared for one session, or null. */
+    /** Pending or linked requirement conversation prepared for one session, or null. */
     getRequirementSession(sessionId) {
         const row = this.#db
-            .prepare('SELECT * FROM requirement_sessions WHERE session_id = ?')
+            .prepare("SELECT * FROM discussion_sessions WHERE subject_type = 'requirement' AND session_id = ?")
             .get(sessionId);
         return row === undefined ? null : toRequirementSession(row);
     }
     /** The requirement linked to a session, whichever kind of link it is. */
     getRequirementBySession(sessionId) {
         const row = this.#db
-            .prepare('SELECT requirement_id FROM requirement_sessions WHERE session_id = ?')
+            .prepare("SELECT subject_id FROM discussion_sessions WHERE subject_type = 'requirement' AND session_id = ?")
             .get(sessionId);
-        return row === undefined ? null : this.getRequirement(text(row, 'requirement_id'));
+        return row === undefined ? null : this.getRequirement(text(row, 'subject_id'));
+    }
+    /** The discussion row bound to one session, or null when none exists. */
+    getDiscussionSession(sessionId) {
+        const rows = this.#db
+            .prepare('SELECT * FROM discussion_sessions WHERE session_id = ?')
+            .all(sessionId);
+        return rows.length === 1 ? toDiscussionSession(rows[0]) : null;
     }
     /**
-     * Conversations under one requirement, newest linked first.
+     * Discussions under one subject, newest linked first.
      *
-     * Pending design rows are excluded by default so the workbench never shows a
-     * session the Agent has not started; tests and diagnostics can opt in.
+     * Pending rows are excluded by default so the workbench never shows a session
+     * the Agent has not started; tests and diagnostics can opt in.
+     */
+    listDiscussionSessions(subjectType, subjectId, options = {}) {
+        const values = [subjectType, subjectId];
+        let kindsClause = '';
+        if (options.kinds !== undefined && options.kinds.length > 0) {
+            kindsClause = ` AND kind IN (${options.kinds.map(() => '?').join(',')})`;
+            values.push(...options.kinds);
+        }
+        const rows = this.#db
+            .prepare(`SELECT * FROM discussion_sessions
+          WHERE subject_type = ? AND subject_id = ?
+            AND (linked_at IS NOT NULL OR ? = 1)${kindsClause}
+          ORDER BY COALESCE(linked_at, prepared_at, created_at) DESC, session_id`)
+            .all(...values.slice(0, 2), options.includeUnlinked === true ? 1 : 0, ...values.slice(2));
+        return rows.map(toDiscussionSession);
+    }
+    /**
+     * Requirement conversations under one requirement, newest linked first.
+     *
+     * The `create` row is always included: it explains where the requirement came
+     * from even though the Agent never confirms it.
      */
     listRequirementSessions(requirementId, options = {}) {
         this.#requireRequirement(requirementId);
         const rows = this.#db
-            .prepare(`SELECT * FROM requirement_sessions
-          WHERE requirement_id = ?
+            .prepare(`SELECT * FROM discussion_sessions
+          WHERE subject_type = 'requirement' AND subject_id = ?
             AND (kind = 'create' OR linked_at IS NOT NULL OR ? = 1)
           ORDER BY kind, COALESCE(linked_at, prepared_at, created_at) DESC, session_id`)
             .all(requirementId, options.includePending === true ? 1 : 0);
@@ -506,10 +606,15 @@ export class WorkflowStore {
             .prepare('SELECT doc_id, story_id FROM design_doc_stories ORDER BY doc_id, created_at, story_id')
             .all();
         const requirementSessions = this.#db
-            .prepare(`SELECT * FROM requirement_sessions
-          WHERE kind = 'create' OR linked_at IS NOT NULL
+            .prepare(`SELECT * FROM discussion_sessions
+          WHERE subject_type = 'requirement' AND (kind = 'create' OR linked_at IS NOT NULL)
           ORDER BY COALESCE(linked_at, created_at) DESC, session_id`)
             .all();
+        const discussionSessions = this.#db
+            .prepare(`SELECT * FROM discussion_sessions
+          WHERE subject_type IN ('story', 'bug') AND linked_at IS NOT NULL
+          ORDER BY COALESCE(linked_at, prepared_at, created_at) DESC, session_id`)
+            .all();
         return {
             requirements: requirements.map(toRequirement),
             stories: stories.map(toStory),
@@ -518,6 +623,7 @@ export class WorkflowStore {
             docs: docs.map(toDesignDoc),
             docStories: docStories.map((row) => ({ docId: text(row, 'doc_id'), storyId: text(row, 'story_id') })),
             requirementSessions: requirementSessions.map(toRequirementSession),
+            discussionSessions: discussionSessions.map(toDiscussionSession),
         };
     }
     /** One detailed-design document by id, or null when it does not exist. */
@@ -531,7 +637,7 @@ export class WorkflowStore {
             const now = this.#now();
             const id = newId('requirement');
             const workspaceId = requiredText(input.workspaceId, 'workspaceId');
-            const contentPath = this.#persistDoc('requirement', workspaceId, { id }, optionalText(input.content));
+            const contentPath = this.#persistDoc('requirement', { id }, optionalText(input.content));
             const requirement = {
                 id,
                 workspaceId,
@@ -634,7 +740,7 @@ export class WorkflowStore {
             }
             const now = this.#now();
             const id = newId('designDoc');
-            const contentPath = this.#persistDoc('designDoc', requirement.workspaceId, { id, requirementId: requirement.id }, optionalText(input.content));
+            const contentPath = this.#persistDoc('designDoc', { id, requirementId: requirement.id }, optionalText(input.content));
             const doc = {
                 id,
                 requirementId: requirement.id,
@@ -662,8 +768,7 @@ export class WorkflowStore {
         return withTransaction(this.#db, () => {
             const current = this.#requireDesignDoc(id);
             if (input.content !== undefined) {
-                const requirement = this.#requireRequirement(current.requirementId);
-                writeDoc(this.#root(requirement.workspaceId), current.contentPath, optionalText(input.content));
+                writeDoc(this.#docsRoot, current.contentPath, optionalText(input.content));
             }
             const next = {
                 ...current,
@@ -762,7 +867,7 @@ export class WorkflowStore {
                 : this.#inheritWorkspace(input.workspaceId, workspaceId, 'story');
             const now = this.#now();
             const id = newId('story');
-            const contentPath = this.#persistDoc('story', storyWorkspaceId, { id }, optionalText(input.content));
+            const contentPath = this.#persistDoc('story', { id }, optionalText(input.content));
             const sessionId = optionalText(input.sessionId);
             const story = {
                 id,
@@ -802,7 +907,7 @@ export class WorkflowStore {
             const size = input.size === undefined ? current.size : sizeOf(input.size);
             const sortOrder = input.sortOrder === undefined ? current.sortOrder : sortOrderOf(input.sortOrder);
             if (input.content !== undefined) {
-                writeDoc(this.#root(current.workspaceId), current.contentPath, optionalText(input.content));
+                writeDoc(this.#docsRoot, current.contentPath, optionalText(input.content));
             }
             this.#db
                 .prepare('UPDATE stories SET title = ?, size = ?, sort_order = ?, updated_at = ? WHERE id = ?')
@@ -1058,7 +1163,7 @@ export class WorkflowStore {
             const bugWorkspaceId = requiredText(input.workspaceId, 'workspaceId');
             const now = this.#now();
             const id = newId('bug');
-            const contentPath = this.#persistDoc('bug', bugWorkspaceId, { id }, optionalText(input.content));
+            const contentPath = this.#persistDoc('bug', { id }, optionalText(input.content));
             const sessionId = optionalText(input.sessionId);
             const bug = {
                 id,
@@ -1093,7 +1198,7 @@ export class WorkflowStore {
             const title = input.title === undefined ? current.title : requiredText(input.title, 'title');
             const severity = input.severity === undefined ? current.severity : severityOf(input.severity);
             if (input.content !== undefined) {
-                writeDoc(this.#root(current.workspaceId), current.contentPath, optionalText(input.content));
+                writeDoc(this.#docsRoot, current.contentPath, optionalText(input.content));
             }
             this.#db
                 .prepare('UPDATE bugs SET title = ?, severity = ?, updated_at = ? WHERE id = ?')
@@ -1184,15 +1289,14 @@ export class WorkflowStore {
                 if (!current.deletable) {
                     throw new WorkflowError(current.reasonCode ?? 'invalid_transition', current.reason ?? `${target.kind} ${target.id} cannot be deleted`);
                 }
-                for (const file of this.#filesToDelete(target)) {
-                    const root = this.#root(file.workspaceId);
+                for (const relative of this.#filesToDelete(target)) {
                     try {
-                        const doc = stageDocDeletion(root, file.relative);
+                        const doc = stageDocDeletion(this.#docsRoot, relative);
                         if (doc !== null)
-                            staged.push({ root, doc });
+                            staged.push({ root: this.#docsRoot, doc });
                     }
                     catch (error) {
-                        throw new WorkflowError('file_error', `could not stage ${file.relative} for deletion: ${describeError(error)}`);
+                        throw new WorkflowError('file_error', `could not stage ${relative} for deletion: ${describeError(error)}`);
                     }
                 }
                 if (target.kind === 'story') {
@@ -1409,23 +1513,16 @@ export class WorkflowStore {
             runCount: 0,
         };
     }
-    /** Files (workspace + relative path) that a successful delete must remove. */
+    /** Document-root-relative paths that a successful delete must remove. */
     #filesToDelete(target) {
-        if (target.kind === 'story') {
-            const story = this.#requireStory(target.id);
-            return [{ workspaceId: story.workspaceId, relative: story.contentPath }];
-        }
-        if (target.kind === 'bug') {
-            const bug = this.#requireBug(target.id);
-            return [{ workspaceId: bug.workspaceId, relative: bug.contentPath }];
-        }
+        if (target.kind === 'story')
+            return [this.#requireStory(target.id).contentPath];
+        if (target.kind === 'bug')
+            return [this.#requireBug(target.id).contentPath];
         const requirement = this.#requireRequirement(target.id);
         return [
-            { workspaceId: requirement.workspaceId, relative: requirement.contentPath },
-            ...this.listDesignDocs(requirement.id).map((doc) => ({
-                workspaceId: requirement.workspaceId,
-                relative: doc.contentPath,
-            })),
+            requirement.contentPath,
+            ...this.listDesignDocs(requirement.id).map((doc) => doc.contentPath),
         ];
     }
     #normalizeTargets(targets) {
@@ -1493,9 +1590,15 @@ export class WorkflowStore {
             throw notFound('requirement', id);
         return toRequirement(row);
     }
+    #requireSubject(subjectType, subjectId) {
+        const table = subjectType === 'requirement' ? 'requirements' : subjectType === 'story' ? 'stories' : 'bugs';
+        const row = this.#db.prepare(`SELECT id FROM ${table} WHERE id = ?`).get(subjectId);
+        if (row === undefined)
+            throw notFound(subjectType, subjectId);
+    }
     #bindRequirementSessionInTx(requirementId, sessionId, createdAt) {
         const existing = this.#db
-            .prepare('SELECT * FROM requirement_sessions WHERE session_id = ?')
+            .prepare("SELECT * FROM discussion_sessions WHERE subject_type = 'requirement' AND session_id = ?")
             .get(sessionId);
         if (existing !== undefined) {
             const row = toRequirementSession(existing);
@@ -1505,9 +1608,9 @@ export class WorkflowStore {
             return row;
         }
         this.#db
-            .prepare(`INSERT INTO requirement_sessions
-           (requirement_id, session_id, kind, prepared_at, linked_at, created_at)
-         VALUES (?, ?, 'create', NULL, NULL, ?)`)
+            .prepare(`INSERT INTO discussion_sessions
+           (subject_type, subject_id, session_id, kind, prepared_at, linked_at, created_at)
+         VALUES ('requirement', ?, ?, 'create', NULL, NULL, ?)`)
             .run(requirementId, sessionId, createdAt);
         return {
             requirementId,
@@ -1520,13 +1623,23 @@ export class WorkflowStore {
     }
     #requireRequirementSession(sessionId) {
         const row = this.#db
-            .prepare('SELECT * FROM requirement_sessions WHERE session_id = ?')
+            .prepare("SELECT * FROM discussion_sessions WHERE subject_type = 'requirement' AND session_id = ?")
             .get(sessionId);
         if (row === undefined) {
             throw new WorkflowError('not_found', `session ${sessionId} is not prepared for a requirement discussion; start again from the requirement page`);
         }
         return toRequirementSession(row);
     }
+    #requireDiscussionSession(sessionId, subjectType, subjectId) {
+        const row = this.#db
+            .prepare(`SELECT * FROM discussion_sessions
+          WHERE subject_type = ? AND subject_id = ? AND session_id = ?`)
+            .get(subjectType, subjectId, sessionId);
+        if (row === undefined) {
+            throw new WorkflowError('not_found', `session ${sessionId} is not prepared for a ${subjectType} discussion`);
+        }
+        return toDiscussionSession(row);
+    }
     #requireStory(id) {
         const row = this.#db.prepare('SELECT * FROM stories WHERE id = ?').get(id);
         if (row === undefined)
@@ -1550,7 +1663,7 @@ export class WorkflowStore {
         const title = input.title === undefined ? current.title : requiredText(input.title, 'title');
         const summary = input.summary === undefined ? current.summary : optionalText(input.summary);
         if (input.content !== undefined) {
-            writeDoc(this.#root(current.workspaceId), current.contentPath, optionalText(input.content));
+            writeDoc(this.#docsRoot, current.contentPath, optionalText(input.content));
         }
         this.#db
             .prepare('UPDATE requirements SET title = ?, summary = ?, updated_at = ? WHERE id = ?')

package/lib/tools/get-bug.js

@@ -24,7 +24,7 @@ export function readBug(workflow, rawId) {
     const bug = workflow.getBug(id);
     if (bug === null)
         throw new Error(`teamflow: 缺陷 ${id} 不存在，无法读取正文。`);
-    const body = workflow.readContent(bug.workspaceId, bug.contentPath);
+    const body = workflow.readContent(bug.contentPath);
     return {
         id: bug.id,
         title: bug.title,

package/lib/tools/get-design-doc.js

@@ -33,7 +33,7 @@ export function readDesignDoc(workflow, rawId) {
     if (requirement === null) {
         throw new Error(`teamflow: 详细设计 ${id} 所属的需求 ${doc.requirementId} 不存在。`);
     }
-    const body = workflow.readContent(requirement.workspaceId, doc.contentPath);
+    const body = workflow.readContent(doc.contentPath);
     return {
         id: doc.id,
         requirementId: doc.requirementId,

package/lib/tools/get-requirement.js

@@ -110,7 +110,7 @@ export function getRequirementTool(environment) {
             }
             const docs = environment.database.workflow.listDesignDocs(requirement.id);
             const stories = environment.database.workflow.listStories({ requirementId: requirement.id });
-            const body = environment.database.workflow.readContent(requirement.workspaceId, requirement.contentPath);
+            const body = environment.database.workflow.readContent(requirement.contentPath);
             return {
                 requirementId: requirement.id,
                 title: requirement.title,

package/lib/tools/get-story.js

@@ -47,7 +47,7 @@ export function readStory(workflow, rawId) {
             path: doc.contentPath,
             coversStory: linked.has(doc.id),
         }));
-    const body = workflow.readContent(story.workspaceId, story.contentPath);
+    const body = workflow.readContent(story.contentPath);
     return {
         id: story.id,
         title: story.title,

package/lib/tools/index.js

@@ -12,6 +12,7 @@ import { getDesignDocTool } from "./get-design-doc.js";
 import { getRequirementTool } from "./get-requirement.js";
 import { getStoryTool } from "./get-story.js";
 import { linkRequirementSessionTool } from "./link-requirement-session.js";
+import { linkSessionTool } from "./link-session.js";
 import { listRecordsTool } from "./list-records.js";
 import { listWorkspacesTool } from "./list-workspaces.js";
 import { createToolEnvironment } from "./shared.js";
@@ -43,6 +44,7 @@ export const TOOL_PROFILES = [
  */
 export const PROFILE_TOOL_NAMES = {
     requirement: [
+        'teamflow_link_session',
         'teamflow_link_requirement_session',
         'teamflow_create_requirement',
         'teamflow_get_requirement',
@@ -51,6 +53,7 @@ export const PROFILE_TOOL_NAMES = {
         'teamflow_list_workspaces',
     ],
     detail: [
+        'teamflow_link_session',
         'teamflow_link_requirement_session',
         'teamflow_get_requirement',
         'teamflow_get_design_doc',
@@ -60,6 +63,7 @@ export const PROFILE_TOOL_NAMES = {
         'teamflow_list_workspaces',
     ],
     split: [
+        'teamflow_link_session',
         'teamflow_link_requirement_session',
         'teamflow_get_requirement',
         'teamflow_get_design_doc',
@@ -80,6 +84,7 @@ export const PROFILE_TOOL_NAMES = {
         'teamflow_cancel_run',
     ],
     bug: [
+        'teamflow_link_session',
         'teamflow_create_bug',
         'teamflow_get_bug',
         'teamflow_update_bug',
@@ -94,6 +99,7 @@ export const PROFILE_TOOL_NAMES = {
         'teamflow_update_design_doc',
         'teamflow_get_design_doc',
         'teamflow_link_requirement_session',
+        'teamflow_link_session',
         'teamflow_create_story',
         'teamflow_get_story',
         'teamflow_update_story',
@@ -138,6 +144,7 @@ export function apply(ctx, config) {
         updateDesignDocTool(environment),
         getDesignDocTool(environment),
         linkRequirementSessionTool(environment),
+        linkSessionTool(environment),
         createStoryTool(environment),
         getStoryTool(environment),
         updateStoryTool(environment),

package/lib/tools/link-session.d.ts

@@ -0,0 +1,3 @@
+import type { ToolEnvironment } from './shared.ts';
+/** Build the generic session-linking tool bound to one Host context. */
+export declare function linkSessionTool(environment: ToolEnvironment): import("@deepseek-ai/dsh-tools").ToolDefinition;