termdock 1.4.309 → 1.4.310

package/dist/server/architecture/store.js

@@ -0,0 +1,502 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { createHash, randomUUID } from 'node:crypto';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import YAML from 'yaml';
+import { ARCHITECTURE_FIELDS, ARCHITECTURE_FILE, ARCHITECTURE_DIRECTORY, analysisFile, architectureScope, isArchitectureFile, isArchitectureSourcePath, parseArchitecture } from './document.js';
+import { parseFlowchart } from './flowchart.js';
+import { diffArchitecture } from './documentDiff.js';
+const runFile = promisify(execFile);
+const digest = (value) => createHash('sha256').update(value).digest('hex');
+const missing = (error) => error?.code === 'ENOENT';
+const safeName = (name) => /^[a-zA-Z][a-zA-Z0-9_-]{0,79}$/.test(name);
+const names = Object.fromEntries(ARCHITECTURE_FIELDS.map(field => [field, field === 'diagram' ? 'diagram.mmd' : `${field}.md`]));
+export class ArchitectureConflict extends Error {
+}
+/** Bound all document IO to real project directories; refuse symlinks in document trees. */
+export class ArchitectureStore {
+    root;
+    constructor(root) {
+        this.root = root;
+    }
+    async bounded(relative, create = false) {
+        if (!relative || relative.startsWith('/') || /[\\\x00-\x1f]/.test(relative) || relative.split('/').some(part => !part || part === '.' || part === '..'))
+            throw new Error('Unsafe architecture path');
+        const root = await fs.realpath(this.root);
+        let current = root;
+        const parts = relative.split('/');
+        for (let index = 0; index < parts.length; index++) {
+            current = path.join(current, parts[index]);
+            try {
+                const stat = await fs.lstat(current);
+                if (stat.isSymbolicLink())
+                    throw new Error('Architecture paths cannot contain symlinks');
+            }
+            catch (error) {
+                if (!missing(error))
+                    throw error;
+                if (create && index < parts.length - 1)
+                    await fs.mkdir(current).catch(async (error) => { if (error.code !== 'EEXIST' || !(await fs.lstat(current)).isDirectory())
+                        throw error; });
+            }
+        }
+        return current;
+    }
+    async text(relative) {
+        const target = await this.bounded(relative);
+        try {
+            const stat = await fs.stat(target);
+            if (!stat.isFile() || stat.size > 5_000_000)
+                throw new Error('Architecture file exceeds the read limit');
+            return await fs.readFile(target, 'utf8');
+        }
+        catch (error) {
+            if (missing(error))
+                return null;
+            throw error;
+        }
+    }
+    async atomic(relative, content) {
+        const target = await this.bounded(relative, true), temp = `${target}.${randomUUID()}.tmp`;
+        try {
+            await fs.writeFile(temp, content, { flag: 'wx', mode: 0o600 });
+            await fs.rename(temp, target);
+        }
+        finally {
+            await fs.rm(temp, { force: true });
+        }
+    }
+    async locked(operation) {
+        const lock = await this.bounded('.termdock/architecture.lock', true);
+        let handle;
+        const deadline = Date.now() + 10_000;
+        while (!handle) {
+            try {
+                handle = await fs.open(lock, 'wx', 0o600);
+                await handle.writeFile(JSON.stringify({ pid: process.pid, time: Date.now() }));
+            }
+            catch (error) {
+                if (error.code !== 'EEXIST')
+                    throw error;
+                if (Date.now() >= deadline)
+                    throw new ArchitectureConflict('Another architecture update is in progress');
+                try {
+                    const owner = JSON.parse(await fs.readFile(lock, 'utf8'));
+                    try {
+                        process.kill(owner.pid, 0);
+                    }
+                    catch (error) {
+                        if (error.code === 'ESRCH') {
+                            await fs.rm(lock, { force: true });
+                            continue;
+                        }
+                    }
+                }
+                catch { /* A newly created lock may not yet contain its owner. */ }
+                await new Promise(resolve => setTimeout(resolve, 30));
+            }
+        }
+        try {
+            return await operation();
+        }
+        finally {
+            await handle.close();
+            await fs.rm(lock, { force: true });
+        }
+    }
+    async list() {
+        const result = [];
+        if (await this.text(ARCHITECTURE_FILE))
+            result.push(ARCHITECTURE_FILE);
+        const folder = await this.bounded(ARCHITECTURE_DIRECTORY);
+        try {
+            for (const entry of await fs.readdir(folder, { withFileTypes: true }))
+                if (entry.isFile() && isArchitectureFile(`${ARCHITECTURE_DIRECTORY}/${entry.name}`))
+                    result.push(`${ARCHITECTURE_DIRECTORY}/${entry.name}`);
+        }
+        catch (error) {
+            if (!missing(error))
+                throw error;
+        }
+        try {
+            if ((await fs.readdir(await this.bounded('.omm'), { withFileTypes: true })).some(entry => entry.isDirectory() && safeName(entry.name)))
+                result.push('.omm');
+        }
+        catch (error) {
+            if (!missing(error))
+                throw error;
+        }
+        return result.sort();
+    }
+    async read(file = ARCHITECTURE_FILE) {
+        if (!isArchitectureFile(file))
+            throw new Error('Invalid architecture document');
+        if (file === '.omm')
+            return this.readOmm();
+        const content = await this.text(file);
+        return { document: content ? parseArchitecture(content) : null, revision: content ? digest(content) : null };
+    }
+    async git() {
+        try {
+            const [{ stdout: gitCommit }, { stdout: gitBranch }] = await Promise.all([runFile('git', ['rev-parse', '--short', 'HEAD'], { cwd: this.root, timeout: 2000 }), runFile('git', ['branch', '--show-current'], { cwd: this.root, timeout: 2000 })]);
+            return { gitCommit: gitCommit.trim(), gitBranch: gitBranch.trim() };
+        }
+        catch {
+            return {};
+        }
+    }
+    historyDirectory(file) { return `.termdock/architecture-history/${digest(file).slice(0, 24)}`; }
+    async archive(file, previous) {
+        if (!previous.document)
+            return;
+        const folder = this.historyDirectory(file);
+        const id = `${Date.now()}-${randomUUID()}`;
+        await this.atomic(`${folder}/${id}.json`, JSON.stringify(previous.document, null, 2));
+        const entries = (await fs.readdir(await this.bounded(folder))).filter(name => /^\d+-[a-f0-9-]+\.json$/.test(name)).sort().reverse();
+        for (const old of entries.slice(30))
+            await fs.unlink(await this.bounded(`${folder}/${old}`));
+    }
+    async history(file) {
+        if (!isArchitectureFile(file))
+            throw new Error('Invalid architecture document');
+        const current = await this.read(file);
+        if (!current.document)
+            return [];
+        const folder = this.historyDirectory(file);
+        let entries;
+        try {
+            entries = (await fs.readdir(await this.bounded(folder))).filter(name => /^\d+-[a-f0-9-]+\.json$/.test(name)).sort().reverse().slice(0, 30);
+        }
+        catch (error) {
+            if (missing(error))
+                return [];
+            throw error;
+        }
+        return Promise.all(entries.map(async (name) => {
+            const previous = parseArchitecture((await this.text(`${folder}/${name}`)));
+            return { id: name.slice(0, -5), savedAt: previous.generatedAt, changes: diffArchitecture(previous, current.document) };
+        }));
+    }
+    async historical(file, id) {
+        if (!isArchitectureFile(file) || !/^\d+-[a-f0-9-]+$/.test(id))
+            throw new Error('Invalid architecture version');
+        const content = await this.text(`${this.historyDirectory(file)}/${id}.json`);
+        if (!content)
+            throw new Error('Architecture version not found');
+        return parseArchitecture(content);
+    }
+    async save(file, input, expectedRevision) {
+        if (!isArchitectureFile(file) || file === '.omm')
+            throw new Error('Use field writes for .omm documents');
+        const document = parseArchitecture(JSON.stringify(input));
+        if (document.analysis && analysisFile(document.analysis) !== file)
+            throw new Error('Architecture scope does not match its file');
+        return this.locked(async () => {
+            const previous = await this.read(file);
+            if (expectedRevision !== undefined && previous.revision !== expectedRevision)
+                throw new ArchitectureConflict('Architecture changed; reload before saving');
+            const changes = diffArchitecture(previous.document, document);
+            if (previous.document && !changes.length && ['summary', 'analysis', 'details', 'origin'].every(key => JSON.stringify(previous.document[key]) === JSON.stringify(document[key])))
+                return previous;
+            await this.archive(file, previous);
+            const now = new Date().toISOString(), git = await this.git();
+            document.generatedAt = now;
+            document.meta = { ...previous.document?.meta, created: previous.document?.meta?.created ?? now, updated: now, updateCount: (previous.document?.meta?.updateCount ?? 0) + 1, ...git };
+            for (const view of document.perspectives) {
+                const oldView = previous.document?.perspectives.find(old => old.id === view.id);
+                view.meta = !oldView || changes.some(change => change.perspective === view.id) ? { created: oldView?.meta?.created ?? now, updated: now, updateCount: (oldView?.meta?.updateCount ?? 0) + 1, ...git, ...(oldView?.diagram ? { previousDiagram: oldView.diagram } : {}) } : oldView.meta;
+                for (const node of view.nodes) {
+                    const old = oldView?.nodes.find(old => old.id === node.id);
+                    if (!old || changes.some(change => change.perspective === view.id && change.node === node.id))
+                        node.meta = { created: old?.meta?.created ?? now, updated: now, updateCount: (old?.meta?.updateCount ?? 0) + 1, ...git, ...(old?.diagram ? { previousDiagram: old.diagram } : {}) };
+                    else
+                        node.meta = old.meta;
+                }
+            }
+            const content = JSON.stringify(document, null, 2);
+            await this.atomic(file, content);
+            return { document, revision: digest(content) };
+        });
+    }
+    ommPath(element) {
+        if (!element || element.split('/').length > 12 || !element.split('/').every(safeName))
+            throw new Error('Invalid .omm element path');
+        return `.omm/${element}`;
+    }
+    async ommElements() {
+        const result = [];
+        const walk = async (relative, depth) => {
+            if (depth > 12 || result.length > 2400)
+                throw new Error('.omm tree exceeds the architecture limit');
+            let entries;
+            try {
+                entries = await fs.readdir(await this.bounded(relative), { withFileTypes: true });
+            }
+            catch (error) {
+                if (missing(error))
+                    return;
+                throw error;
+            }
+            for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+                if (!safeName(entry.name))
+                    continue;
+                if (entry.isSymbolicLink())
+                    throw new Error('.omm tree cannot contain symlinks');
+                if (entry.isDirectory()) {
+                    const next = `${relative}/${entry.name}`;
+                    result.push(next.slice(5));
+                    await walk(next, depth + 1);
+                }
+            }
+        };
+        await walk('.omm', 0);
+        return result;
+    }
+    async readOmmFields(element) {
+        const base = this.ommPath(element), fields = {};
+        for (const field of ARCHITECTURE_FIELDS) {
+            const value = await this.text(`${base}/${names[field]}`);
+            if (value !== null)
+                fields[field] = value;
+        }
+        const raw = await this.text(`${base}/meta.yaml`);
+        if (!raw)
+            return fields;
+        const m = YAML.parse(raw, { maxAliasCount: 10 });
+        const meta = {};
+        for (const [from, to] of [['created', 'created'], ['updated', 'updated'], ['git_commit', 'gitCommit'], ['git_branch', 'gitBranch'], ['prev_diagram', 'previousDiagram']])
+            if (typeof m?.[from] === 'string')
+                meta[to] = m[from];
+        if (typeof m?.update_count === 'number' && Number.isSafeInteger(m.update_count) && m.update_count >= 0)
+            meta.updateCount = m.update_count;
+        return { ...fields, meta };
+    }
+    async validateOmmMerge(files) {
+        const temporary = await fs.mkdtemp(path.join(os.tmpdir(), 'termdock-omm-import-'));
+        try {
+            const stage = new ArchitectureStore(temporary), merged = { ...(await this.exportOmmBundle()).files, ...files };
+            for (const [name, value] of Object.entries(merged))
+                await stage.atomic(`.omm/${name}`, value);
+            const result = await stage.readOmm();
+            if (!result.document)
+                throw new Error('Bundle contains no architecture perspectives');
+        }
+        finally {
+            await fs.rm(temporary, { recursive: true, force: true });
+        }
+    }
+    async writeOmmField(element, field, content, expectedRevision) {
+        if (!ARCHITECTURE_FIELDS.includes(field) || typeof content !== 'string' || content.length > 100_000)
+            throw new Error('Invalid architecture field');
+        const base = this.ommPath(element);
+        if (field === 'diagram') {
+            const issues = parseFlowchart(content).issues.filter(issue => !issue.startsWith('Connection needs'));
+            if (issues.length)
+                throw new Error(issues.join('\n'));
+        }
+        return this.locked(async () => {
+            const previous = await this.readOmm();
+            if (expectedRevision !== undefined && previous.revision !== expectedRevision)
+                throw new ArchitectureConflict('Architecture changed; reload before saving');
+            const old = await this.readOmmFields(element);
+            if (old[field] === content)
+                return previous;
+            await this.validateOmmMerge({ [`${element}/${names[field]}`]: content });
+            await this.archive('.omm', previous);
+            const now = new Date().toISOString();
+            const git = await this.git();
+            // Field writes preserve the upstream file layout and metadata convention.
+            await this.atomic(`${base}/${names[field]}`, content);
+            const meta = { created: old.meta?.created ?? now, updated: now, update_count: (old.meta?.updateCount ?? 0) + 1,
+                last_field: field, git_commit: git.gitCommit, git_branch: git.gitBranch,
+                ...(field === 'diagram' && old.diagram ? { prev_diagram: old.diagram } : old.meta?.previousDiagram ? { prev_diagram: old.meta.previousDiagram } : {}) };
+            await this.atomic(`${base}/meta.yaml`, YAML.stringify(meta));
+            return this.readOmm();
+        });
+    }
+    async deleteOmmElement(element) { const target = this.ommPath(element); await this.locked(async () => { await this.archive('.omm', await this.readOmm()); await fs.rm(await this.bounded(target), { recursive: true, force: false }); }); }
+    async readOmm() {
+        const elements = await this.ommElements();
+        if (!elements.length)
+            return { document: null, revision: null };
+        const data = new Map();
+        let total = 0;
+        for (let offset = 0; offset < elements.length; offset += 16) {
+            for (const [element, fields] of await Promise.all(elements.slice(offset, offset + 16).map(async (element) => [element, await this.readOmmFields(element)]))) {
+                total += Buffer.byteLength(JSON.stringify(fields), 'utf8');
+                if (total > 5_000_000)
+                    throw new Error('.omm documentation exceeds the read limit');
+                data.set(element, fields);
+            }
+        }
+        const perspectives = [];
+        const uid = (element) => `e_${digest(element).slice(0, 20)}`;
+        const label = (value) => value.replace(/-/g, ' ').replace(/^\w/, ch => ch.toUpperCase());
+        const links = [];
+        for (const perspective of elements.filter(element => !element.includes('/'))) {
+            const fields = data.get(perspective);
+            const nodes = new Map(), edges = [];
+            const add = async (element, parentId, diagramLabel) => {
+                const old = nodes.get(element);
+                if (old)
+                    return old;
+                const entry = data.get(element) ?? {};
+                const lines = (diagramLabel ?? '').split('\n');
+                const files = [];
+                for (const line of lines.slice(1)) {
+                    const relative = line.trim();
+                    if (isArchitectureSourcePath(relative)) {
+                        try {
+                            if ((await fs.stat(await this.bounded(relative))).isFile())
+                                files.push({ path: relative });
+                        }
+                        catch { /* Documentation can reference a directory or a removed file. */ }
+                    }
+                }
+                const node = { id: uid(element), documentPath: element, title: lines[0]?.replace(/^@/, '') || label(element.split('/').pop()), summary: (entry.description ?? '').replace(/[#*`]/g, '').split(/\n\s*\n/)[0].slice(0, 600), files, ...entry, ...(parentId ? { parentId } : {}) };
+                nodes.set(element, node);
+                const graph = parseFlowchart(entry.diagram ?? '');
+                for (const child of graph.nodes) {
+                    const childElement = `${element}/${child.id}`, childNode = await add(childElement, node.id, child.label);
+                    childNode.role = child.role;
+                    if (child.ref)
+                        links.push({ node: childNode, target: child.ref });
+                }
+                for (const edge of graph.edges)
+                    edges.push({ from: uid(`${element}/${edge.from}`), to: uid(`${element}/${edge.to}`), label: edge.label });
+                // Include documented children even if an old diagram has not mentioned them yet.
+                for (const child of elements.filter(child => child.startsWith(`${element}/`) && child.slice(element.length + 1).indexOf('/') === -1))
+                    await add(child, node.id);
+                return node;
+            };
+            const graph = parseFlowchart(fields.diagram ?? '');
+            for (const child of graph.nodes) {
+                const node = await add(`${perspective}/${child.id}`, undefined, child.label);
+                node.role = child.role;
+                if (child.ref)
+                    links.push({ node, target: child.ref });
+            }
+            for (const child of elements.filter(child => child.startsWith(`${perspective}/`) && child.split('/').length === 2))
+                await add(child);
+            for (const edge of graph.edges)
+                edges.push({ from: uid(`${perspective}/${edge.from}`), to: uid(`${perspective}/${edge.to}`), label: edge.label });
+            if (!nodes.size)
+                nodes.set(perspective, { id: uid(perspective), title: label(perspective), summary: fields.description ?? '', files: [], ...fields });
+            perspectives.push({ id: perspective, title: label(perspective), summary: (fields.description ?? '').split(/\n\s*\n/)[0].slice(0, 600), nodes: [...nodes.values()], edges, ...fields });
+        }
+        for (const link of links)
+            if (perspectives.some(view => view.id === link.target))
+                link.node.references = [...(link.node.references ?? []), { perspective: link.target }];
+        const generatedAt = [...data.values()].map(value => value.meta?.updated).filter((value) => !!value && Number.isFinite(Date.parse(value))).sort().pop() ?? new Date(0).toISOString();
+        const document = parseArchitecture(JSON.stringify({ version: 1, origin: 'omm', generatedAt, summary: `${path.basename(this.root)} architecture`, perspectives }));
+        const config = await this.text('.omm/config.yaml');
+        return { document, revision: digest(JSON.stringify([...data]) + (config ?? '')) };
+    }
+    async config(language) {
+        const raw = await this.text('.omm/config.yaml');
+        const config = raw ? YAML.parse(raw, { maxAliasCount: 10 }) : { version: '0.1.0', language: 'en' };
+        if (!config || typeof config !== 'object' || Array.isArray(config))
+            throw new Error('Invalid .omm configuration');
+        if (language !== undefined) {
+            if (!/^[a-z]{2}(?:-[A-Z]{2})?$/.test(language))
+                throw new Error('Invalid language');
+            config.language = language;
+            await this.locked(() => this.atomic('.omm/config.yaml', YAML.stringify(config)));
+        }
+        return { language: typeof config?.language === 'string' ? config.language : 'en' };
+    }
+    async exportOmmBundle(document) {
+        const files = {};
+        if (!document) {
+            for (const element of await this.ommElements()) {
+                for (const name of [...Object.values(names), 'meta.yaml']) {
+                    const value = await this.text(`.omm/${element}/${name}`);
+                    if (value !== null)
+                        files[`${element}/${name}`] = value;
+                }
+            }
+            const config = await this.text('.omm/config.yaml');
+            if (config)
+                files['config.yaml'] = config;
+        }
+        else {
+            files['config.yaml'] = YAML.stringify({ version: '0.1.0' });
+            for (const view of document.perspectives) {
+                const elementPath = (node) => {
+                    const ids = [], visited = new Set();
+                    while (node) {
+                        if (visited.has(node.id))
+                            throw new Error('Cyclic architecture');
+                        visited.add(node.id);
+                        ids.unshift(node.id);
+                        node = view.nodes.find(parent => parent.id === node.parentId);
+                    }
+                    return [view.id, ...ids].join('/');
+                };
+                for (const item of [view, ...view.nodes]) {
+                    const node = item === view ? undefined : item, base = elementPath(node), scope = architectureScope(view, node?.id);
+                    for (const field of ARCHITECTURE_FIELDS) {
+                        const value = item[field] ?? (field === 'description' ? item.summary : undefined);
+                        if (value !== undefined && field !== 'diagram')
+                            files[`${base}/${names[field]}`] = value;
+                    }
+                    if (scope.nodes.length) {
+                        const label = (value) => value.replace(/["<>|`\\\r\n]/g, ' ');
+                        files[`${base}/diagram.mmd`] = ['graph LR', ...scope.nodes.map(child => `${child.id}["${child.references?.[0]?.perspective ? `@${child.references[0].perspective}` : label(child.title)}${child.files.length ? `\\n${child.files.map(file => file.path).join('\\n')}` : ''}"]`), ...scope.edges.map(edge => `${edge.from} -->|"${label(edge.label)}"| ${edge.to}`), ...scope.nodes.filter(child => child.role).map(child => `class ${child.id} ${child.role}`)].join('\n');
+                    }
+                    else if (item.diagram)
+                        files[`${base}/diagram.mmd`] = item.diagram;
+                    const meta = item.meta ?? { created: document.generatedAt, updated: document.generatedAt, updateCount: 0 };
+                    files[`${base}/meta.yaml`] = YAML.stringify({ created: meta.created, updated: meta.updated, update_count: meta.updateCount, git_commit: meta.gitCommit, git_branch: meta.gitBranch, prev_diagram: meta.previousDiagram });
+                }
+            }
+        }
+        if (Buffer.byteLength(JSON.stringify(files), 'utf8') > 5_000_000)
+            throw new Error('Export exceeds the architecture limit');
+        return { format: 'termdock-omm-bundle', version: 1, files };
+    }
+    async importOmmBundle(input, expectedRevision) {
+        const bundle = input;
+        if (bundle?.format !== 'termdock-omm-bundle' || bundle.version !== 1 || !bundle.files || typeof bundle.files !== 'object' || Array.isArray(bundle.files))
+            throw new Error('Invalid .omm bundle');
+        const files = Object.entries(bundle.files);
+        if (!files.length || files.length > 16_801 || Buffer.byteLength(JSON.stringify(input), 'utf8') > 5_000_000)
+            throw new Error('Invalid .omm bundle size');
+        for (const [name, value] of files) {
+            const parts = name.split('/'), filename = parts.pop();
+            if (!(name === 'config.yaml' || (parts.length > 0 && parts.length <= 12 && parts.every(safeName) && [...Object.values(names), 'meta.yaml'].includes(filename))) || typeof value !== 'string' || value.length > 100_000)
+                throw new Error(`Unsafe .omm bundle file: ${name}`);
+            await this.bounded(`.omm/${name}`);
+            if (filename?.endsWith('.yaml'))
+                YAML.parse(value, { maxAliasCount: 10 });
+        }
+        await this.locked(async () => {
+            const previous = await this.readOmm();
+            if (expectedRevision !== undefined && previous.revision !== expectedRevision)
+                throw new ArchitectureConflict('Architecture changed; reload before importing');
+            // Validate the merged tree in isolation before touching the project's documents.
+            await this.validateOmmMerge(Object.fromEntries(files));
+            await this.archive('.omm', previous);
+            // A bundle merges explicit files, preserving unrelated existing perspectives.
+            // Every destination is checked before the first write; no business files are touched.
+            const undo = [];
+            try {
+                for (const [name, value] of files) {
+                    undo.push([name, await this.text(`.omm/${name}`)]);
+                    await this.atomic(`.omm/${name}`, value);
+                }
+            }
+            catch (error) {
+                for (const [name, value] of undo.reverse()) {
+                    if (value === null)
+                        await fs.rm(await this.bounded(`.omm/${name}`), { force: true });
+                    else
+                        await this.atomic(`.omm/${name}`, value);
+                }
+                throw error;
+            }
+        });
+    }
+}

package/dist/server/cli.js

@@ -10,6 +10,10 @@ import { resolve } from 'path';
 // dotenv 不会覆盖已存在的环境变量，因此系统环境变量和命令行参数优先级最高
 loadDotenv({ path: resolve(os.homedir(), '.termdock', '.env'), quiet: true });
 loadDotenv({ path: resolve(process.cwd(), '.env'), quiet: true });
+if (['architecture', 'arch'].includes(process.argv[2] ?? '')) {
+    const { runArchitectureCli } = await import('./architecture/cli.js');
+    process.exit(await runArchitectureCli(process.argv.slice(3)));
+}
 // Federation commands run before normal server/terminal CLI initialization.
 if (process.argv.slice(2).some(arg => arg === '--federation-pairing' || arg === '--federation-relay')) {
     const { runFederationCli } = await import('./federation/cli.js');
@@ -199,6 +203,8 @@ Options:
   -h, --help         Show this help message
 
 Short commands:
+  architecture       Analyze, browse and edit recursive project architecture
+                     (see td architecture --help)
   agent-plugin [--json]
                      Explain how an Agent integrates itself. JSON mode is
                      machine-readable and intended for Agent consumption.
@@ -2112,7 +2118,7 @@ function runPluginInitJson() {
         collaboration: {
             capabilities: 'Optional routing hints shown beside this Agent in collaboration groups.',
             universalTransport: 'Every detected Agent receives durable inbox messages through its PTY and can use td collab when it has shell access.',
-            hooks: 'Hooks add busy/idle awareness so Termdock can defer delivery until a turn finishes; they are not required for collaboration.',
+            hooks: 'Hooks publish declared lifecycle/status events; collaboration does not wait for an idle phase and does not require hooks.',
         },
         security: {
             source: 'Only public HTTPS repository roots on approved Git hosts or explicit local paths are accepted; URL credentials are rejected.',

package/dist/server/entry.js

@@ -38,6 +38,7 @@ import { exitWithStartupFailure } from './utils/startupFailure.js';
 import { androidRecordings } from './android/recording.js';
 import { stopAllScrcpySessions } from './android/scrcpy.js';
 import filesystemRoutes from './routes/filesystem.js';
+import { architectureRoutes } from './architecture/routes.js';
 import authRoutes from './routes/auth.js';
 import notificationRoutes from './routes/notifications.js';
 import { createOnboardingRouter } from './routes/onboarding.js';
@@ -346,6 +347,7 @@ export function createApp(options = {}) {
     app.use('/api/terminal', terminalRoutes);
     // 文件系统路由（继承 /api/terminal 上的 auth + CSRF 保护）
     app.use('/api/terminal/fs', filesystemRoutes);
+    app.use('/api/terminal/architecture', architectureRoutes());
     // 本机 Android 设备桥接（adb/scrcpy）。经加密隧道时按业务 API 处理，
     // 仅全权服务授权可达；投屏 WS 在 federation runtime 中按 full-service 校验。
     app.use('/api/android', requireAuth({ bypass: isTrustedLocalCliRequest }));

package/dist/server/federation/accessPolicy.js

@@ -40,7 +40,7 @@ const fileReads = new Set(['list', 'watch', 'search', 'read', 'git-blob', 'eda-p
 const filePosts = new Set(['git-action', 'apply-hunk', 'upload', 'open-in-file-browser']);
 const settings = new Set(['settings', 'toolbar-presets', 'program-detection', 'context-draft']);
 const serviceReads = new Set(['update', 'auto-title/catalog', 'agent-hooks', 'agent-launchers', 'agent-plugins', 'quota', 'tmux/status', 'tmux/sessions', 'agent-resume-history']);
-const reservedSessionIds = new Set(['fs', 'settings', 'client-state', 'session-inventory', 'operations', 'tmux', 'create', 'force-kill', 'serialize-state', 'agent-resume-history', 'toolbar-presets', 'context-draft', 'program-detection', 'update', 'quota', 'agent-hooks', 'agent-launchers', 'agent-plugins', 'agent-plugin-icon', 'auto-title', 'directory-suggestions']);
+const reservedSessionIds = new Set(['architecture', 'fs', 'settings', 'client-state', 'session-inventory', 'operations', 'tmux', 'create', 'force-kill', 'serialize-state', 'agent-resume-history', 'toolbar-presets', 'context-draft', 'program-detection', 'update', 'quota', 'agent-hooks', 'agent-launchers', 'agent-plugins', 'agent-plugin-icon', 'auto-title', 'directory-suggestions']);
 export function resolveAccessRequest(method, path) {
     if (!isBusinessApiPath(method, path))
         return null;
@@ -57,6 +57,14 @@ export function resolveAccessRequest(method, path) {
     if (!pathname.startsWith(prefix))
         return null;
     const route = pathname.slice(prefix.length);
+    if (route.startsWith('architecture/')) {
+        const op = route.slice('architecture/'.length);
+        if (read && ['documents', 'document', 'history', 'version', 'bundle'].includes(op))
+            return { action: 'file.read' };
+        if (method === 'PUT' && ['document', 'field', 'bundle'].includes(op))
+            return { action: 'file.write' };
+        return null;
+    }
     if (route.startsWith('fs/')) {
         const op = route.slice(3);
         if (read && (fileReads.has(op) || /^preview\/.+/.test(op)))

package/docs/integrations.md

@@ -209,6 +209,46 @@ td integration update --file /private/policy.json
 未配置 `startupInput` 的旧 profile 保留原投递方式；TD 不猜测各家 TUI 的加载画面。
 管理员 CLI 会先读取运行服务能力，旧服务缺接口或能力时失败，不会忽略条件后继续配置。
 
+### 清除既有会话的屏幕启动条件（1.4.310）
+
+从策略中删除 `startupInput` 只影响新会话，既有会话仍保留原启动快照。需要让指定
+旧会话使用普通终端投递时，由本机管理员通过正式入口显式解除：
+
+```sh
+# 先由持有该会话的身份回读当前 generation
+td collab --principal report-bridge session get <TD-session-id>
+# 本机管理员执行，不使用 principal 凭据；generation 必须取当前实际值
+td integration clear-startup-input <TD-session-id> --generation <N>
+td collab --principal report-bridge session get <TD-session-id>
+```
+
+最低 CLI / 实际服务版本均为 **1.4.310**；先回读能力
+`session_startup_input_clear=true`、`session_startup_input_clear_min_version=1.4.310`。
+CLI 在旧服务上返回 `SESSION_STARTUP_INPUT_CLEAR_UNSUPPORTED`，不尝试修改私有文件。
+本机认证接口为 `POST /admin/sessions/:id/startup-input/clear`，请求仅含
+`{"generation":N}`，回复 `{session: …}`；集成 principal 无权调用这个管理员入口。
+
+操作原子持久化删除该记录的 `profile.startupInput`、`startup_condition` 和
+`startup_input`，设置公开字段 **`startup_input_disabled=true`**，generation 增加 1。
+以后对该逻辑会话执行实际 restore 也不重新继承 profile 的屏幕条件；新创建的其它
+会话仍按各自策略启动。此入口只支持显式禁用，不提供重新启用或更换启动配置。
+原逻辑 ID / 原生 UUID / argv / model / cwd / 包装器 / 配置指纹 / operation ID /
+终端绑定 / 消息历史及 reply 关联保持原状，不启动、退出或重建 Agent。
+会话事件仍使用现有 `session.<state>`，payload 带更新后的 session / generation /
+`startup_input_disabled`，沿原持久订阅与 ACK 机制推送。
+
+管理员解除条件后，**已经 pending 的消息可能随下一次投递继续发送**；不重发
+`delivered` 正文。它解除的是额外画面限制，不证明 Agent 输入已初始化、已读、空闲
+或已消费，`delivered` 仍只表示终端写入，结果仍看明确回复。运行中亦可执行，
+不需要修改窗口尺寸或等待模型/footer 文案。
+
+原子保存失败不解除条件。代次不匹配返回 `SESSION_GENERATION_MISMATCH`，缺失或
+非法代次返回 `INVALID_SESSION_GENERATION`；有启动/恢复/释放进行中或结果不明时
+返回 `SESSION_OPERATION_IN_PROGRESS`；记录不存在返回 `INTEGRATION_SESSION_NOT_FOUND`。
+用新 generation 对已禁用会话重复清除是 no-op，不再增加代次；旧 generation 仍
+拒绝。若命令回执丢失，先 get 查证新代次与禁用字段，不盲重试旧参数。既有 release /
+restore 幂等键的历史结果保持不变，以 get 为当前状态依据。
+
 ## 版本与能力核验
 
 ```sh

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "termdock",
-  "version": "1.4.309",
+  "version": "1.4.310",
   "description": "A complete web-based terminal application with modern UI",
   "type": "module",
   "main": ".desktop-dist/main.js",
@@ -12,6 +12,7 @@
     ".": "./dist/server/entry.js"
   },
   "files": [
+    "THIRD_PARTY_NOTICES.md",
     "dist",
     "runtime-manifest.json",
     "README.md",
@@ -101,6 +102,7 @@
     "uuid": "^13.0.0",
     "web-push": "^3.6.7",
     "ws": "^8.21.0",
+    "yaml": "^2.9.1",
     "zustand": "^4.5.0"
   },
   "devDependencies": {