@xirang-ai/dsh-teamflow 0.1.0 → 0.1.2

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";

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;