@youcloud/mantis-mcp 0.0.0-stage → 1.0.0

package/dist/workflow/operations.js

@@ -0,0 +1,123 @@
+import { mkdir, open, readFile, rename, unlink, chmod } from 'node:fs/promises';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { WorkflowError } from './contracts.js';
+import { digest } from './tokens.js';
+const processStart = `${process.pid}:${Date.now() - Math.round(process.uptime() * 1000)}:${randomUUID()}`;
+const retention = 7 * 86400_000;
+export class Operations {
+    dir;
+    constructor(root) { this.dir = join(root, 'operations'); }
+    async initialize() {
+        await mkdir(this.dir, { recursive: true, mode: 0o700 });
+        await chmod(this.dir, 0o700);
+    }
+    async load(id) {
+        if (!/^[a-f0-9-]{36}$/i.test(id))
+            throw new WorkflowError('INVALID_INPUT', '操作编号无效');
+        try {
+            const record = JSON.parse(await readFile(join(this.dir, `${id}.json`), 'utf8'));
+            if (record.operation_id !== id || !Array.isArray(record.steps) || !record.plan || !record.request_hash
+                || record.resolved_hash !== digest(record.plan))
+                throw new Error('invalid');
+            return record;
+        }
+        catch (e) {
+            if (e.code === 'ENOENT')
+                return null;
+            throw new WorkflowError('RECOVERY_UNAVAILABLE', '操作账本不可读取或已损坏，禁止重新发送');
+        }
+    }
+    expired(record) { return Date.now() - (record.completed_at ?? record.created_at) > retention; }
+    async save(record) {
+        await this.initialize();
+        record.updated_at = Date.now();
+        const temp = join(this.dir, `${record.operation_id}.${randomUUID()}.tmp`);
+        const handle = await open(temp, 'wx', 0o600);
+        try {
+            await handle.writeFile(JSON.stringify(record));
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        try {
+            await rename(temp, join(this.dir, `${record.operation_id}.json`));
+            const directory = await open(this.dir, 'r');
+            try {
+                await directory.sync();
+            }
+            finally {
+                await directory.close();
+            }
+        }
+        finally {
+            await unlink(temp).catch(() => { });
+        }
+    }
+    async lock(key) {
+        await this.initialize();
+        if (!/^[a-z0-9-]+$/i.test(key))
+            throw new WorkflowError('INVALID_INPUT', '锁对象无效');
+        const path = join(this.dir, `${key}.lock`);
+        const owner = { pid: process.pid, process_start: processStart, token: randomUUID() };
+        const claim = async () => {
+            try {
+                const handle = await open(path, 'wx', 0o600);
+                try {
+                    await handle.writeFile(JSON.stringify(owner));
+                    await handle.sync();
+                }
+                finally {
+                    await handle.close();
+                }
+                return async () => {
+                    const current = JSON.parse(await readFile(path, 'utf8').catch(() => '{}'));
+                    if (current.token === owner.token)
+                        await unlink(path);
+                };
+            }
+            catch (e) {
+                if (e.code === 'EEXIST')
+                    return null;
+                throw e;
+            }
+        };
+        const release = await claim();
+        if (release)
+            return release;
+        // 用独立回收锁串行化崩溃恢复。仍存活或 PID 已复用时保守地不抢锁。
+        let reaper;
+        try {
+            reaper = await open(`${path}.reaper`, 'wx', 0o600);
+        }
+        catch {
+            return null;
+        }
+        try {
+            let old;
+            try {
+                old = JSON.parse(await readFile(path, 'utf8'));
+            }
+            catch {
+                return null;
+            }
+            if (!Number.isSafeInteger(old.pid) || old.pid <= 0)
+                return null;
+            try {
+                process.kill(old.pid, 0);
+                return null;
+            }
+            catch (e) {
+                if (e.code !== 'ESRCH')
+                    return null;
+            }
+            await unlink(path);
+            return await claim();
+        }
+        finally {
+            await reaper.close();
+            await unlink(`${path}.reaper`).catch(() => { });
+        }
+    }
+}

package/dist/workflow/planner.js

@@ -0,0 +1,209 @@
+import { enumValue, numberConfig } from './bindings.js';
+import { WorkflowError } from './contracts.js';
+import { digest } from './tokens.js';
+import { operationMarker } from '../services/notes.js';
+import { readUpload } from '../services/files.js';
+import { facts, visibleCollection } from '../services/issues.js';
+const labels = { accept_issue: '受理缺陷', assign_issue: '指派缺陷', submit_fix: '登记修复及研发自测（待测试验收）',
+    close_issue: '测试验收通过并关闭', reopen_issue: '重开缺陷', reject_issue: '拒绝本次缺陷处置', postpone_issue: '延期处理' };
+export class Planner {
+    context;
+    uploadDir;
+    constructor(context, uploadDir) {
+        this.context = context;
+        this.uploadDir = uploadDir;
+    }
+    async version(project, id) {
+        const version = (await this.context.projects.versions(project, true)).find(v => v.id === id);
+        if (!version)
+            throw new WorkflowError('PROJECT_MISMATCH', '版本不属于当前项目的可用版本');
+        return version.name;
+    }
+    async prepare(action, input, session) {
+        if (action.endsWith('_version'))
+            return { plan: await this.versionPlan(action, input, session) };
+        const c = this.context;
+        const state = action === 'report_issue' ? undefined : await c.state(input.issue_id);
+        const issue = state?.issue;
+        const projectId = issue?.project.id ?? input.project_id;
+        const project = await c.projects.get(projectId);
+        const rules = state?.rules ?? (action === 'report_issue' ? await c.projects.rules(projectId) : undefined);
+        const binding = c.bindingRevision(rules);
+        if (input.expected_revision && issue)
+            session.tokens.check(input.expected_revision, `issue:${issue.id}`, binding, issue);
+        const plan = { project_id: projectId, issue_id: issue?.id, kind: 'issue', method: 'PATCH', path: `issues/${issue?.id}`,
+            primary: 'update_issue', expected: {}, body: {}, before_hash: digest(issue ?? null), before_facts: issue ? facts(issue, session.baseUrl) : {},
+            revision: issue ? c.revision(session, issue, binding, state?.etag) : {}, etag: state?.etag, binding };
+        if (action === 'upload_file') {
+            const file = await readUpload(input.file_path, input.filename, input.expected_file_sha256, this.uploadDir);
+            const latest = (await c.issues.get(issue.id)).issue;
+            if (digest(latest) !== plan.before_hash)
+                throw new WorkflowError('REVISION_CONFLICT', '读取附件期间缺陷发生变化', true);
+            plan.method = 'POST';
+            plan.path += '/files';
+            plan.primary = 'upload_file';
+            plan.body = undefined;
+            plan.file = file.info;
+            plan.attachment_ids = visibleCollection(issue, 'attachments', state.emptyArraysOmitted)?.map((a) => a.id);
+            if (!Array.isArray(plan.attachment_ids))
+                throw new WorkflowError('SERVICE_UNAVAILABLE', '无法取得附件比较基线');
+            return { plan, bytes: file.bytes };
+        }
+        if (['delete_issue', 'delete_note', 'remove_relationship', 'remove_monitor', 'detach_tag'].includes(action)) {
+            plan.method = 'DELETE';
+            plan.primary = action;
+            plan.body = undefined;
+            const target = action === 'delete_note' ? ['notes', 'note_id'] : action === 'remove_relationship' ? ['relationships', 'relationship_id']
+                : action === 'remove_monitor' ? ['monitors', 'username'] : action === 'detach_tag' ? ['tags', 'tag_id'] : undefined;
+            if (target) {
+                const [section, key] = target;
+                const entry = issue[section]?.find((v) => key === 'username' ? v.name === input[key] : v.id === input[key]);
+                if (!entry)
+                    throw new WorkflowError('NOT_FOUND_OR_NOT_VISIBLE', '删除对象不属于该缺陷或当前不可见');
+                plan.path += `/${section}/${encodeURIComponent(String(input[key]))}`;
+                plan.expected = { removed_section: section, removed_id: input[key] };
+                if (action === 'remove_monitor') {
+                    // 2.26.2 没有 DELETE monitors 路由；mc_issue_update 支持显式 monitors 集合。
+                    // 只移除已核对的目标，保留其余 ID，仍受完整快照前置检查保护。
+                    plan.method = 'PATCH';
+                    plan.path = `issues/${issue.id}`;
+                    plan.body = { monitors: issue.monitors.filter((v) => v.id !== entry.id).map((v) => ({ id: v.id })) };
+                    plan.expected.remaining_monitor_ids = plan.body.monitors.map((v) => v.id);
+                }
+            }
+            return { plan };
+        }
+        if (!rules)
+            throw new WorkflowError('WORKFLOW_MAPPING_UNCONFIGURED', '该动作依赖的项目配置不可读取');
+        if (action === 'report_issue') {
+            if (!project.categories?.some((v) => v.id === input.category_id))
+                throw new WorkflowError('PROJECT_MISMATCH', '分类不属于当前项目');
+            plan.method = 'POST';
+            plan.path = 'issues';
+            plan.primary = 'create_issue';
+            plan.body = { project: { id: projectId }, category: { id: input.category_id }, summary: input.summary,
+                description: [input.description, `【预期行为】\n${input.expected_behavior}`, `【实际行为】\n${input.actual_behavior}`,
+                    ...(input.environment ? [`【环境】\n${input.environment}`] : [])].join('\n\n'),
+                additional_information: operationMarker(input.operation_id) };
+            if (input.steps_to_reproduce)
+                plan.body.steps_to_reproduce = input.steps_to_reproduce;
+            if (input.version_id)
+                plan.body.version = { name: await this.version(projectId, input.version_id) };
+        }
+        else if (action === 'add_note') {
+            plan.method = 'POST';
+            plan.path += '/notes';
+            plan.primary = 'append_note';
+            plan.body = { text: `${input.text}\n\n${operationMarker(input.operation_id)}`, view_state: { name: this.noteVisibility(projectId, rules, input) } };
+        }
+        else {
+            const target = action === 'assign_issue' ? {} : c.bindings.target(projectId, action, rules);
+            if (action === 'accept_issue') {
+                if (issue.status?.id >= numberConfig(rules, 'bug_resolved_status_threshold'))
+                    throw new WorkflowError('INVALID_INPUT', '已解决缺陷须按实际原因重开后再受理');
+                plan.body.status = { id: input.assignee ? target.assigned_status_id : issue.status?.id === target.assigned_status_id ? target.assigned_status_id : target.status_id };
+            }
+            else if (action !== 'assign_issue') {
+                plan.body.status = { id: target.status_id };
+                if (target.resolution_id)
+                    plan.body.resolution = { id: target.resolution_id };
+            }
+            if (action === 'reject_issue')
+                plan.body.resolution = { id: target.resolutions_by_reason[input.reason_code] };
+            if (action === 'close_issue') {
+                const fixed = c.bindings.target(projectId, 'submit_fix', rules);
+                if (issue.resolution?.id !== fixed.resolution_id)
+                    throw new WorkflowError('INVALID_INPUT', '验收关闭仅用于修复结果，不得关闭拒绝或延期问题');
+            }
+            if (action === 'reopen_issue' && input.reason_code === 'resume_postponed') {
+                const postponed = c.bindings.target(projectId, 'postpone_issue', rules);
+                if (issue.status?.id !== postponed.status_id || issue.resolution?.id !== postponed.resolution_id)
+                    throw new WorkflowError('INVALID_INPUT', '只有延期缺陷可使用恢复延期分支');
+            }
+            if (input.assignee) {
+                const userId = input.assignee === 'me' ? session.user.id : input.assignee;
+                if (!(await c.projects.members(projectId)).some(u => u.id === userId))
+                    throw new WorkflowError('PROJECT_MISMATCH', '负责人不是当前可见项目成员');
+                plan.body.handler = { id: userId };
+            }
+            if (input.fixed_in_version_id)
+                plan.body.fixed_in_version = { name: await this.version(projectId, input.fixed_in_version_id) };
+            if (input.target_version_id)
+                plan.body.target_version = { name: await this.version(projectId, input.target_version_id) };
+            const verificationVersion = input.verification?.version_id ?? input.verification_context?.version_id;
+            if (verificationVersion)
+                await this.version(projectId, verificationVersion);
+            const sections = [`【${labels[action]}】`];
+            if (input.reason_code)
+                sections.push(`处置类型：${input.reason_code}`);
+            for (const [key, label] of Object.entries({ reason: '原因', fix_summary: '修复说明', root_cause: '根因', actual_behavior: '实际现象', review_on: '计划复查日期（不自动提醒）' })) {
+                if (input[key])
+                    sections.push(`${label}：${input[key]}`);
+            }
+            if (input.self_test)
+                sections.push(`研发自测（调用者提供，MCP 未执行测试）：${input.self_test.summary}\n结果：passed`, ...this.evidence(input.self_test.evidence));
+            if (input.verification)
+                sections.push(`测试验收：${input.verification.summary}\n结果：passed`, `验收环境/版本：${JSON.stringify(input.verification.environment ?? input.verification.version_id)}`, ...this.evidence(input.verification.evidence));
+            if (input.verification_context)
+                sections.push(`验证环境/版本：${JSON.stringify(input.verification_context)}`);
+            if (input.code_refs)
+                sections.push(`代码引用：${JSON.stringify(input.code_refs)}`);
+            sections.push(...this.evidence(input.evidence), operationMarker(input.operation_id));
+            plan.note = { text: sections.join('\n\n'), view_state: { name: this.noteVisibility(projectId, rules, input) } };
+        }
+        for (const key of ['priority', 'severity', 'reproducibility']) {
+            if (input[`${key}_id`]) {
+                enumValue(rules, key, input[`${key}_id`]);
+                plan.body[key] = { id: input[`${key}_id`] };
+            }
+        }
+        const registered = c.bindings.forProject(projectId).custom_fields_by_action;
+        const allowed = registered[action] ?? [];
+        const provided = input.custom_fields ?? [];
+        if (new Set(provided.map((f) => f.id)).size !== provided.length || provided.some((f) => !allowed.some(a => a.id === f.id))
+            || allowed.some(f => f.required && !provided.some((p) => p.id === f.id)))
+            throw new WorkflowError('INVALID_INPUT', '自定义字段未登记、重复或缺少必填值');
+        if (provided.length)
+            plan.body.custom_fields = provided.map((f) => ({ field: { id: f.id }, value: f.value }));
+        if (action !== 'add_note')
+            plan.expected = { ...plan.body };
+        return { plan };
+    }
+    evidence(e) { return (e ?? []).map(v => `证据（${v.kind}）：${v.value}`); }
+    noteVisibility(projectId, rules, input) {
+        if (input.note_view_state)
+            return input.note_view_state;
+        const policy = this.context.bindings.forProject(projectId).note_visibility;
+        if (policy !== 'instance_default')
+            return policy;
+        const value = numberConfig(rules, 'default_bugnote_view_status');
+        const name = enumValue(rules, 'view_state', value).name;
+        if (!['public', 'private'].includes(name))
+            throw new WorkflowError('WORKFLOW_MAPPING_INVALID', '项目默认备注可见性无法可靠解析');
+        return name;
+    }
+    async versionPlan(action, input, session) {
+        const c = this.context;
+        await c.projects.get(input.project_id);
+        const versions = await c.projects.versions(input.project_id);
+        if (action !== 'create_version' && !versions.some(v => v.id === input.version_id))
+            throw new WorkflowError('PROJECT_MISMATCH', '版本不属于该项目，继承版本请使用所属项目编号');
+        if (input.expected_revision)
+            session.tokens.check(input.expected_revision, `versions:${input.project_id}`, c.bindings.revision, versions);
+        const body = {};
+        for (const key of ['name', 'description', 'released', 'obsolete', 'timestamp'])
+            if (input[key] !== undefined)
+                body[key] = input[key];
+        if (action === 'release_version') {
+            body.released = true;
+            body.timestamp = input.timestamp ?? new Date().toISOString();
+        }
+        return { kind: 'version', project_id: input.project_id, version_id: input.version_id,
+            path: `projects/${input.project_id}/versions${action === 'create_version' ? '' : `/${input.version_id}`}`,
+            method: action === 'create_version' ? 'POST' : action === 'delete_version' ? 'DELETE' : 'PATCH', primary: action,
+            body: action === 'delete_version' ? undefined : body, expected: body, before_hash: digest(versions), before_facts: {},
+            unchanged_versions_hash: digest(versions.filter(v => v.id !== input.version_id)),
+            revision: session.tokens.revision(`versions:${input.project_id}`, c.bindings.revision, versions), binding: c.bindings.revision,
+            next_version: input.next_version };
+    }
+}

package/dist/workflow/query.js

@@ -0,0 +1,98 @@
+import { RestError } from '../client.js';
+import { WorkflowError } from './contracts.js';
+import { digest } from './tokens.js';
+import { numberConfig } from './bindings.js';
+import { facts } from '../services/issues.js';
+export const conservativeCapabilities = { nativeAssigned: false, verifiedUpdatedSort: false, conditionalRequests: false };
+export async function queryIssues(context, input, session, capabilities) {
+    await context.projects.get(input.project_id);
+    const rules = await context.projects.rules(input.project_id);
+    const binding = context.bindingRevision(rules);
+    const { cursor: _cursor, ...query } = input;
+    const queryHash = digest(query);
+    const c = input.cursor ? session.tokens.open(input.cursor) : undefined;
+    if (c && (c.kind !== 'query_cursor' || c.subject !== `project:${input.project_id}` || c.query !== queryHash || c.binding !== binding)) {
+        throw new WorkflowError('STALE_CURSOR', '列表游标与查询或项目配置不符');
+    }
+    const person = (value) => value === 'me' ? session.user.id : value;
+    const assignee = person(input.assignee), reporter = person(input.reporter);
+    const threshold = input.queue === 'unresolved' ? numberConfig(rules, 'bug_resolved_status_threshold') : undefined;
+    const target = input.queue === 'awaiting_verification' ? context.bindings.target(input.project_id, 'submit_fix', rules)
+        : input.queue === 'postponed' ? context.bindings.target(input.project_id, 'postpone_issue', rules) : undefined;
+    const wantsNative = input.assignee === 'me' && input.queue === 'unresolved' && !input.filter_id;
+    let native = c ? c.native === true : wantsNative && capabilities.nativeAssigned;
+    let page = Number(c?.page ?? 1), offset = Number(c?.offset ?? 0);
+    const warnings = ['DYNAMIC_SOURCE_NOT_SNAPSHOT'];
+    if (wantsNative && !native)
+        warnings.push('NATIVE_FILTER_UNAVAILABLE');
+    let scanned = 0, matched = 0, exhausted = false;
+    const items = [], seen = new Set();
+    while (scanned < 500 && items.length < input.limit) {
+        let source;
+        try {
+            source = await context.issues.page(input.project_id, page, input.filter_id ?? (native ? 'assigned' : undefined));
+        }
+        catch (e) {
+            if (native && !c && scanned === 0 && e instanceof RestError && [400, 404, 422].includes(e.status ?? 0)) {
+                native = false;
+                page = 1;
+                offset = 0;
+                warnings.push('NATIVE_FILTER_UNAVAILABLE');
+                continue;
+            }
+            if (!scanned)
+                throw e;
+            warnings.push('SOURCE_READ_FAILED');
+            break;
+        }
+        if (native && source.some(i => i.project?.id !== input.project_id || i.handler?.id !== session.user.id || !(i.status?.id < threshold))) {
+            if (c || scanned)
+                throw new WorkflowError('NATIVE_FILTER_UNAVAILABLE', '原生筛选返回不符合契约，须从首页重新查询');
+            native = false;
+            warnings.push('NATIVE_FILTER_UNAVAILABLE');
+            continue;
+        }
+        if (!source.length) {
+            exhausted = true;
+            break;
+        }
+        for (; offset < source.length && scanned < 500 && items.length < input.limit; offset++) {
+            const issue = source[offset];
+            scanned++;
+            if (!Number.isSafeInteger(issue.id) || !Number.isSafeInteger(issue.project?.id) || !Number.isSafeInteger(issue.status?.id)
+                || !Number.isSafeInteger(issue.resolution?.id))
+                throw new WorkflowError('SERVICE_UNAVAILABLE', '源列表缺少必需过滤字段，不能报告完整查询');
+            if (issue.project.id !== input.project_id || assignee && issue.handler?.id !== assignee || reporter && issue.reporter?.id !== reporter)
+                continue;
+            if (threshold !== undefined && issue.status.id >= threshold)
+                continue;
+            if (target && (issue.status.id !== target.status_id || issue.resolution.id !== target.resolution_id))
+                continue;
+            const date = Date.parse(issue.updated_at);
+            if ((input.updated_after || input.updated_before) && !Number.isFinite(date))
+                throw new WorkflowError('SERVICE_UNAVAILABLE', '源列表缺少有效更新时间');
+            if (input.updated_after && date < Date.parse(input.updated_after) || input.updated_before && date > Date.parse(input.updated_before))
+                continue;
+            matched++;
+            if (!seen.has(issue.id)) {
+                items.push(facts(issue, session.baseUrl));
+                seen.add(issue.id);
+            }
+        }
+        if (offset >= source.length) {
+            if (source.length < 100) {
+                exhausted = true;
+                break;
+            }
+            page++;
+            offset = 0;
+        }
+    }
+    return { schema_version: 1, items, returned_count: items.length, scanned_count: scanned, matched_in_scan_count: matched,
+        scan_limit_reached: scanned >= 500 && !exhausted, source_exhausted: exhausted,
+        next_cursor: exhausted ? null : session.tokens.seal({ kind: 'query_cursor', subject: `project:${input.project_id}`, binding,
+            query: queryHash, page, offset, native }),
+        filter_execution: { server: input.filter_id ? 'saved_filter' : native ? 'assigned' : 'project', client: 'intersection', native_assigned_verified: native },
+        sort_execution: native && capabilities.verifiedUpdatedSort ? 'verified_updated_desc' : 'source_order_unverified',
+        warnings, total_count: null, snapshot_consistent: false };
+}

package/dist/workflow/tokens.js

@@ -0,0 +1,72 @@
+import { createHash, createCipheriv, createDecipheriv, randomBytes } from 'node:crypto';
+import { WorkflowError } from './contracts.js';
+export function canonical(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonical).join(',')}]`;
+    if (value && typeof value === 'object')
+        return `{${Object.entries(value).filter(([, v]) => v !== undefined)
+            .sort(([a], [b]) => a.localeCompare(b)).map(([k, v]) => `${JSON.stringify(k)}:${canonical(v)}`).join(',')}}`;
+    return JSON.stringify(value) ?? 'null';
+}
+export const digest = (value) => createHash('sha256').update(canonical(value)).digest('hex');
+export const revisionLifetime = 30 * 60 * 1000;
+/** 加密而非裸 JSON 游标，防止泄露快照和服务端 ETag；每次使用前必须重新认证。 */
+export class Tokens {
+    key;
+    principal;
+    constructor(key, principal) {
+        this.key = key;
+        this.principal = principal;
+    }
+    seal(value) {
+        const nonce = randomBytes(12);
+        const cipher = createCipheriv('aes-256-gcm', this.key, nonce);
+        const data = Buffer.concat([cipher.update(JSON.stringify({ ...value, principal: this.principal, expires: value.expires ?? Date.now() + revisionLifetime })), cipher.final()]);
+        return Buffer.concat([nonce, cipher.getAuthTag(), data]).toString('base64url');
+    }
+    open(raw, allowExpired = false) {
+        try {
+            if (raw.length > 16000)
+                throw new Error();
+            const data = Buffer.from(raw, 'base64url');
+            const decipher = createDecipheriv('aes-256-gcm', this.key, data.subarray(0, 12));
+            decipher.setAuthTag(data.subarray(12, 28));
+            const value = JSON.parse(Buffer.concat([decipher.update(data.subarray(28)), decipher.final()]).toString());
+            if (value.principal !== this.principal || !Number.isFinite(value.expires) || (!allowExpired && value.expires <= Date.now()))
+                throw new Error();
+            return value;
+        }
+        catch {
+            throw new WorkflowError('STALE_CURSOR', '标识无效、已过期或不属于当前主体');
+        }
+    }
+    revision(subject, binding, snapshot, etag) {
+        const expires = Date.now() + revisionLifetime;
+        return { expected_revision: this.seal({ kind: 'revision', subject, binding, snapshot: digest(snapshot), etag: etag ?? null, expires }),
+            revision_expires_at: new Date(expires).toISOString() };
+    }
+    check(raw, subject, binding, snapshot) {
+        try {
+            const t = this.open(raw);
+            if (t.kind !== 'revision' || t.subject !== subject || t.binding !== binding || t.snapshot !== digest(snapshot))
+                throw new Error();
+            return t;
+        }
+        catch {
+            throw new WorkflowError('REVISION_CONFLICT', '前置标识已过期、绑定变更或对象事实改变，请重新读取 context', true);
+        }
+    }
+    compare(raw, subject, binding, snapshot) {
+        if (!raw)
+            return 'not_requested';
+        try {
+            const t = this.open(raw, true);
+            if (t.kind !== 'revision' || t.subject !== subject || t.binding !== binding)
+                return 'unavailable';
+            return t.snapshot === digest(snapshot) ? 'unchanged' : 'changed';
+        }
+        catch {
+            return 'unavailable';
+        }
+    }
+}

package/docs/clients.md

@@ -0,0 +1,142 @@
+# MCP 客户端接入
+
+[返回 README](../README.md) · [服务配置](configuration.md) · [调用手册](cookbook.md)
+
+以下示例均启动本地 stdio 服务。使用变量引用的示例，需先在**启动客户端的环境**中设置并导出 `MANTIS_BASE_URL`、`MANTIS_API_KEY`，配置中的引用保持原样，不替换成真实 Key。Trae 示例通过 Node.js 加载本机私有环境文件，见对应小节。仅在编辑器的集成终端中设置变量，通常不能更新已经运行的编辑器进程；具体检查方法见[连接排障](#连接排障)。
+
+已有配置文件时，只合并 `mantis` 条目，保留其他服务。各客户端的顶层字段和变量引用语法不同，请使用对应示例：
+
+| 客户端 | 配置入口 | 凭据传入方式 |
+|---|---|---|
+| [Codex](#codex) | `~/.codex/config.toml` | `env_vars` 转发变量名 |
+| [Claude Code](#claude-code) | 项目根目录 `.mcp.json` | `env` 中使用 `${变量名}` |
+| [Cursor](#cursor) | `~/.cursor/mcp.json` 或项目 `.cursor/mcp.json` | `env` 中使用 `${env:变量名}` |
+| [Trae](#trae) | 设置 > MCP > 手动添加，或项目 `.trae/mcp.json` | Node.js `--env-file` 加载本机私有环境文件 |
+
+标准 Mantis 部署无需 `MANTIS_WORKFLOW_CONFIG`；需要自定义映射时，再按对应客户端的语法传入该变量，并使用配置文件的绝对路径。对于 `command` 为 `npx` 的示例，已全局安装本包时可以改为 `mantis-mcp` 并移除 `args`；Trae 示例保留 `node` 及其环境文件参数。
+
+客户端运行环境须能找到 Node.js/npm；使用 nvm 或桌面启动器时，确认其 `PATH`，必要时使用可执行文件的绝对路径。SSH、WSL、容器等远程会话中，依赖、环境变量、配置路径及上传文件都应位于**实际运行 MCP 子进程的环境**。
+
+## Codex
+
+在 `~/.codex/config.toml` 中添加以下配置，适用于使用该配置的 Codex CLI、桌面客户端和 IDE 扩展。`env_vars` 填变量名称，实际值来自启动 Codex 的环境。参见 [OpenAI 官方 MCP 文档](https://learn.chatgpt.com/docs/extend/mcp#configure-with-configtoml)。
+
+```toml
+[mcp_servers.mantis]
+command = "npx"
+args = ["-y", "@youcloud/mantis-mcp@1.0.0"]
+env_vars = ["MANTIS_BASE_URL", "MANTIS_API_KEY"]
+startup_timeout_sec = 60
+tool_timeout_sec = 180
+```
+
+使用自定义工作流文件时，将 `MANTIS_WORKFLOW_CONFIG` 加入 `env_vars`。重启 Codex 后，在会话中通过 `/mcp` 查看 `mantis` 的工具。
+
+## Claude Code
+
+在项目根目录的 `.mcp.json` 中添加以下配置。Claude Code 在加载时展开 `${变量名}`，因此配置文件可以保留变量引用。参见 [Claude Code 官方 MCP 文档](https://code.claude.com/docs/en/mcp#environment-variable-expansion-in-mcpjson)。
+
+```json
+{
+  "mcpServers": {
+    "mantis": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@youcloud/mantis-mcp@1.0.0"],
+      "env": {
+        "MANTIS_BASE_URL": "${MANTIS_BASE_URL}",
+        "MANTIS_API_KEY": "${MANTIS_API_KEY}"
+      }
+    }
+  }
+}
+```
+
+从该项目目录启动 `claude`，首次使用按提示批准项目 MCP 服务，然后用 `/mcp` 查看连接状态。也可运行 `claude mcp list` 检查配置；如有缺失变量警告，先补齐启动环境再重启。
+
+## Cursor
+
+跨项目使用时编辑 `~/.cursor/mcp.json`，仅当前项目使用时编辑 `.cursor/mcp.json`。Cursor 使用 `${env:变量名}` 展开环境变量。参见 [Cursor 官方 MCP 文档](https://cursor.com/docs/mcp#config-interpolation)。
+
+```json
+{
+  "mcpServers": {
+    "mantis": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@youcloud/mantis-mcp@1.0.0"],
+      "env": {
+        "MANTIS_BASE_URL": "${env:MANTIS_BASE_URL}",
+        "MANTIS_API_KEY": "${env:MANTIS_API_KEY}"
+      }
+    }
+  }
+}
+```
+
+重启 Cursor 后，在设置中的 MCP 服务列表确认 `mantis` 已启用，再在 Agent 会话中使用其工具。若通过桌面图标启动，确认 Cursor 进程能够取得上述环境变量。
+
+## Trae
+
+在 Trae IDE 的 **设置 > MCP > 添加 > 手动添加** 中配置全局服务；也可通过 **原始配置（JSON）** 打开配置文件。若界面提供运行环境选项，选择**本地**。仅当前项目使用时，先在设置中启用项目级 MCP，再编辑项目根目录的 `.trae/mcp.json`。参见 [Trae 官方 MCP 文档](https://docs.trae.cn/ide_add-mcp-servers)。
+
+Trae 官方文档仅列出 `${workspaceFolder}` 变量替换；本例用 Node.js 的 `--env-file` 读取凭据，MCP JSON 只保存本机路径。
+
+先按 [README 安装说明](../README.md#安装)全局安装本包，运行 `npm root --global` 获取全局模块目录；在该目录后追加 `/@youcloud/mantis-mcp/dist/index.js`，即为下方所需的服务入口路径。然后在项目目录之外创建仅本人可读的 `mantis.env` 文件，在本机填写实际地址和个人 Key：
+
+```dotenv
+MANTIS_BASE_URL=https://mantis.example.org
+MANTIS_API_KEY="替换为你的个人 API Key"
+```
+
+在 Trae 中添加以下 JSON，将 `args` 中的两个路径替换为本机的**完整绝对路径**，不要使用 `~`；Windows 路径可写为 `C:/Users/你的用户名/...`：
+
+```json
+{
+  "mcpServers": {
+    "mantis": {
+      "command": "node",
+      "args": [
+        "--env-file=/绝对路径/mantis.env",
+        "/npm全局模块目录/@youcloud/mantis-mcp/dist/index.js"
+      ],
+      "env": {
+        "START_MCP_TIMEOUT_MS": "60000",
+        "RUN_MCP_TIMEOUT_MS": "180000"
+      }
+    }
+  }
+}
+```
+
+需要自定义映射时，将 `MANTIS_WORKFLOW_CONFIG` 及文件绝对路径加入 `mantis.env`。Node.js 会优先使用进程环境中已有的同名变量，修改凭据后需核对其来源并重启 MCP 服务；参见 [Node.js 环境文件说明](https://nodejs.org/download/release/v22.12.0/docs/api/cli.html#--env-fileconfig)。
+
+保存后在 MCP 列表确认 `mantis` 已启用，并在使用的智能体中启用其工具；自定义智能体需在 **工具 > MCP** 中勾选 `mantis`，参见[官方智能体配置说明](https://docs.trae.cn/ide_use-mcp-servers-in-agents)。最后按下方[验证连接](#验证连接)执行一次只读调用。
+
+## 验证连接
+
+在所选客户端中发送：
+
+> 请调用 mantis 的 get_project_context，参数为 {}，列出当前账号可见的项目。
+
+返回项目列表（允许为空）才表明本次只读访问成功。仅显示“已连接”或列出工具只证明本地服务已启动。
+
+## 连接排障
+
+| 错误码 | 含义与处理 |
+|---|---|
+| `CONFIG_MISSING` | 缺少连接变量，消息只列出缺失名称；HTTP 请求尚未发送 |
+| `CONFIG_INVALID` | 地址或 Key 格式无效；地址须为完整 HTTP(S) 基地址，可含部署子路径或 `/api/rest/` 后缀，不含用户凭据、查询参数或片段；HTTP 请求尚未发送 |
+| `REQUEST_PREPARATION_FAILED` | 本地构造请求失败，HTTP 请求尚未发送；核对输入或提交脱敏错误报告 |
+| `MANTIS_FORBIDDEN` | 服务端返回 HTTP 401/403，核对个人 Key 和账号权限 |
+| `SERVICE_UNAVAILABLE` | 读取未取得可靠结果；网络错误消息按可识别的原因提示 DNS、超时、TLS 或连接类别 |
+| `WRITE_OUTCOME_UNKNOWN` | 写入可能已发生，先按原 `operation_id` 核查，不能仅凭网络错误直接重试 |
+
+Codex 的 `env_vars` 只允许并转发启动环境中已有的变量，不会加载 `.zshrc`。变量在交互终端中存在，不代表已启动的桌面客户端或其 MCP 子进程也能取得。确认使用 `export` 导出变量，并检查**启动客户端的环境**；更新后重启客户端及 MCP 子进程。具体转发语义见 [OpenAI 官方说明](https://learn.chatgpt.com/docs/extend/mcp#stdio-servers)。
+
+可在用于启动客户端的终端中执行以下检查，只输出是否存在，不打印凭据；这不能证明另一个已运行进程的环境相同。
+
+```bash
+node -e 'for (const k of ["MANTIS_BASE_URL", "MANTIS_API_KEY"]) console.log(k + ": " + (process.env[k]?.trim() ? "已设置" : "缺失"))'
+```
+