@youcloud/metersphere-mcp 0.0.0-stage → 1.0.0

package/dist/services/metersphere.js

@@ -0,0 +1,250 @@
+import { createHmac } from 'node:crypto';
+import { ensure } from '../errors.js';
+import { array, executionDefinition, executionSnapshot, object, parseRecord, pick, segment, fieldsMatch, resultBody } from '../adapters/v1-20.js';
+import { executionSchema } from '../workflow/contracts.js';
+import { digest, Tokens } from '../workflow/tokens.js';
+export class MeterSphere {
+    client;
+    config;
+    constructor(client, config) {
+        this.client = client;
+        this.config = config;
+    }
+    async session() {
+        const version = await this.client.read('/system/version');
+        ensure(typeof version === 'string' && /^v1\.20\.23-lts(?:-|$)/.test(version), 'UNSUPPORTED_VERSION', '当前仅验证 v1.20.23-lts 适配；请先核对其他部署版本');
+        const user = object(await this.client.read('/currentUser'), '当前身份');
+        ensure(typeof user.id === 'string' && user.id.length > 0, 'AUTHENTICATION_FAILED', '未取得真实用户 ID');
+        const namespace = digest([this.config.baseUrl, user.id]);
+        const credentials = this.config.credentials();
+        const key = createHmac('sha256', credentials.secretKey).update(`metersphere-mcp:${credentials.accessKey}:${namespace}`).digest();
+        return { user: { id: user.id, name: typeof user.name === 'string' ? user.name : user.id }, namespace,
+            tokens: new Tokens(key, digest([namespace, this.config.workflow])) };
+    }
+    async project(id) {
+        const value = object(await this.client.read(`/project/get/${segment(id)}`), '项目');
+        ensure(value.id === id && typeof value.workspaceId === 'string', 'NOT_FOUND_OR_NOT_VISIBLE', '项目不存在、不可见或缺少工作空间');
+        return value;
+    }
+    async plan(projectId, id) {
+        const value = object(await this.client.read(`/test/plan/get/${segment(id)}`, {}), '计划');
+        ensure(value.id === id && value.projectId === projectId, 'TARGET_MISMATCH', '计划与指定项目不匹配');
+        return value;
+    }
+    async review(projectId, id) {
+        const value = object(await this.client.read(`/test/case/review/get/${segment(id)}`), '评审');
+        ensure(value.id === id && value.projectId === projectId, 'TARGET_MISMATCH', '评审与指定项目不匹配');
+        return value;
+    }
+    async principals(planId) { return array(await this.client.read(`/test/plan/principal/${segment(planId)}`), '计划负责人').map(x => pick(x, ['id', 'name'])); }
+    async reviewers(reviewId) { return array(await this.client.read('/test/case/review/reviewer', { id: reviewId }), '评审人员').map(x => pick(x, ['id', 'name'])); }
+    async case(projectId, id) {
+        const value = object(await this.client.read(`/test/case/get/${segment(id)}`), '用例');
+        ensure(value.id === id && value.projectId === projectId && value.type === 'functional', 'TARGET_MISMATCH', '用例不属于指定项目或不是功能用例');
+        return value;
+    }
+    async reviewCase(projectId, reviewId, row) {
+        ensure(typeof row.id === 'string' && row.id.length > 0 && row.reviewId === reviewId
+            && typeof row.caseId === 'string' && row.caseId.length > 0 && (row.projectId == null || row.projectId === projectId), 'TARGET_MISMATCH', '评审用例关联与指定评审或项目不匹配');
+        // v1.20 的评审列表不选择 project_id，也不按请求 projectId 过滤；通过用例详情核验归属。
+        const item = await this.case(projectId, row.caseId);
+        ensure(row.versionId == null || row.versionId === item.versionId, 'INCOMPLETE_SCOPE', '读取期间评审用例版本已改变，请重新读取');
+        return { ...row, projectId: item.projectId, refId: item.refId };
+    }
+    async planCase(projectId, planId, id) {
+        await this.plan(projectId, planId);
+        return this.planCaseDetail(projectId, planId, id);
+    }
+    async planCaseDetail(projectId, planId, id) {
+        const value = object(await this.client.read(`/test/plan/case/get/${segment(id)}`), '计划用例');
+        ensure(value.id === id && value.projectId === projectId && value.planId === planId && typeof value.caseId === 'string' && value.type === 'functional', 'TARGET_MISMATCH', '计划用例与指定项目/计划不匹配');
+        return value;
+    }
+    async nodes(projectId) { return array(await this.client.read(`/case/node/list/${segment(projectId)}`), '模块树'); }
+    async nodeIndex(projectId) {
+        const seen = new Set();
+        const visit = (nodes, parentId = null, prefix = '', level = 1) => nodes.flatMap(n => {
+            const parent = n.parentId === '0' || n.parentId === '' ? null : n.parentId ?? null;
+            ensure(typeof n.id === 'string' && !seen.has(n.id) && typeof n.name === 'string' && n.projectId === projectId
+                && n.level === level && level <= 8 && parent === parentId, 'SCHEMA_DRIFT', '模块树的项目、父子关系或层级不符合预期');
+            seen.add(n.id);
+            const node = { id: n.id, projectId, name: n.name, parentId: parent, level, path: `${prefix}/${n.name}` };
+            return [node, ...visit(array(n.children ?? [], '子模块'), n.id, node.path, level + 1)];
+        });
+        return visit(await this.nodes(projectId));
+    }
+    async node(projectId, nodeId) {
+        const node = (await this.nodeIndex(projectId)).find(x => x.id === nodeId);
+        ensure(node, 'TARGET_MISMATCH', '模块不属于指定项目');
+        return node;
+    }
+    async moduleLocation(projectId, name, parentId = null) {
+        const nodes = await this.nodeIndex(projectId), parent = parentId === null ? null : nodes.find(x => x.id === parentId);
+        ensure(parentId === null || parent, 'TARGET_MISMATCH', '父模块不存在或不属于指定项目；一级模块请省略 parent_id');
+        const level = parent ? parent.level + 1 : 1;
+        ensure(level <= 8, 'MODULE_DEPTH_LIMIT', '功能用例模块最多支持 8 层，不能在第 8 层下创建子模块');
+        const existing = nodes.find(x => x.parentId === parentId && x.name === name);
+        ensure(!existing, 'MODULE_ALREADY_EXISTS', `同一父模块下已存在同名模块（ID：${existing?.id}），不会自动复用或重复创建`);
+        return { parent: parent ?? null, parent_id: parentId, level, path: `${parent?.path ?? ''}/${name}` };
+    }
+    async members(projectId) { return array(await this.client.read(`/user/project/member/${segment(projectId)}`), '项目人员').map(x => pick(x, ['id', 'name', 'status'])); }
+    async checkMembers(projectId, ids) {
+        const members = await this.members(projectId);
+        ensure(ids.every(id => members.some(x => x.id === id)), 'TARGET_MISMATCH', '指定人员不在项目成员中');
+    }
+    async page(path, body, page = 1, size = 100) {
+        const data = object(await this.client.read(`${path}/${page}/${size}`, body), '分页');
+        const items = array(data.listObject, '分页条目');
+        ensure(Number.isSafeInteger(data.itemCount) && data.itemCount >= 0 && items.length <= size && (!items.length || (page - 1) * size + items.length <= data.itemCount), 'SCHEMA_DRIFT', '分页数量结构无效');
+        return { items, total: data.itemCount };
+    }
+    async all(path, body, cap = this.config.workflow.limits.max_plan_items_for_completion) {
+        const result = [], seen = new Set();
+        let previousTotal;
+        for (let page = 1;; page++) {
+            const data = await this.page(path, body, page, 100);
+            ensure(previousTotal === undefined || previousTotal === data.total, 'INCOMPLETE_SCOPE', '扫描期间总数发生变化，请重新读取');
+            previousTotal = data.total;
+            ensure(data.total <= cap, 'INCOMPLETE_SCOPE', '完整扫描超过配置上限');
+            for (const x of data.items) {
+                ensure(typeof x.id === 'string' && !seen.has(x.id), 'INCOMPLETE_SCOPE', '分页存在重复或缺少 ID，不能当成完整快照');
+                seen.add(x.id);
+                result.push(x);
+            }
+            if (result.length === data.total)
+                return result;
+            ensure(result.length < data.total && data.items.length > 0 && result.length < cap, 'INCOMPLETE_SCOPE', '分页提前结束或数量不一致');
+        }
+    }
+    async query(path, body, input, session, predicate = () => true) {
+        const identity = digest([path, body, { ...input, cursor: undefined }]);
+        const position = input.cursor ? session.tokens.open(input.cursor, 'cursor') : { query: identity, page: 1, offset: 0 };
+        ensure(position.query === identity && Number.isSafeInteger(position.page) && position.page >= 1 && Number.isSafeInteger(position.offset) && position.offset >= 0 && position.offset < 100, 'STALE_CURSOR', '游标与当前查询不一致');
+        const items = [], seen = new Set();
+        let scanned = 0, exhausted = false, sourceTotal = null;
+        let page = position.page, offset = position.offset;
+        const limit = Math.min(input.limit ?? this.config.workflow.limits.default_page_size, this.config.workflow.limits.max_page_size), budget = this.config.workflow.limits.max_scan_items_per_call;
+        outer: while (scanned < budget && items.length < limit) {
+            const data = await this.page(path, body, page, 100);
+            sourceTotal = data.total;
+            if (!data.items.length) {
+                ensure((page - 1) * 100 >= data.total, 'INCOMPLETE_SCOPE', '服务端提前返回空页');
+                exhausted = true;
+                break;
+            }
+            for (; offset < data.items.length; offset++) {
+                if (scanned >= budget || items.length >= limit)
+                    break outer;
+                const value = data.items[offset];
+                scanned++;
+                ensure(typeof value.id === 'string', 'SCHEMA_DRIFT', '列表条目缺少真实 ID');
+                if (await predicate(value) && !seen.has(value.id)) {
+                    items.push(value);
+                    seen.add(value.id);
+                }
+            }
+            if ((page - 1) * 100 + offset >= data.total) {
+                exhausted = true;
+                break;
+            }
+            ensure(data.items.length === 100, 'INCOMPLETE_SCOPE', '非末页条目数量不足，未跳过未知条目');
+            page++;
+            offset = 0;
+        }
+        return { items, returned_count: items.length, scanned_count: scanned, source_exhausted: exhausted,
+            next_cursor: exhausted ? null : session.tokens.seal({ kind: 'cursor', query: identity, page, offset }), source_total_count: sourceTotal,
+            snapshot_consistent: false, filter_execution: 'client_verified', warnings: exhausted ? [] : ['本次结果不是全量；续查游标不保证下一页有匹配项'] };
+    }
+    async comments(caseId) {
+        const comments = array(await this.client.read(`/test/case/comment/list/${segment(caseId)}`), '用例评论');
+        ensure(comments.length <= 2000 && JSON.stringify(comments).length <= 2 * 1024 * 1024, 'INCOMPLETE_HISTORY', '评论超过读取上限，未将截断内容当成完整记录');
+        return comments;
+    }
+    async records(caseId) { return (await this.comments(caseId)).map(parseRecord).filter((x) => !!x); }
+    async caseEditState(projectId, caseId) {
+        const item = await this.case(projectId, caseId);
+        const follows = await this.client.read(`/test/case/follow/${segment(caseId)}`);
+        ensure(Array.isArray(follows) && follows.every(x => typeof x === 'string'), 'SCHEMA_DRIFT', '关注人列表结构无法可靠保留');
+        const files = array(await this.client.read(`/test/case/file/metadata/${segment(caseId)}`), '附件');
+        return { item, follows, files };
+    }
+    async inventory(projectId, planId) {
+        const plan = await this.plan(projectId, planId);
+        const listed = await this.all('/test/plan/case/list', { projectId, planId });
+        ensure(listed.every(x => x.projectId === projectId && x.planId === planId && typeof x.caseId === 'string' && x.type === 'functional'), 'TARGET_MISMATCH', '计划包含其他项目或未知类型的用例');
+        // v1.20 列表不含完整定义和逐步结果；快照与执行评论必须使用同一详情来源。
+        const cases = [];
+        for (const item of listed) {
+            const detail = await this.planCaseDetail(projectId, planId, item.id);
+            ensure(detail.caseId === item.caseId && detail.versionId === item.versionId, 'INCOMPLETE_SCOPE', '读取期间计划用例或版本已改变，请重新读取');
+            cases.push(detail);
+        }
+        const counts = await Promise.all([
+            this.page('/test/plan/api/case/list', { projectId, planId }, 1, 1),
+            this.page('/test/plan/scenario/case/list', { projectId, planId }, 1, 1),
+            this.page('/test/plan/load/case/list', { projectId, testPlanId: planId }, 1, 1),
+        ]);
+        return { plan, cases, other_counts: { api: counts[0].total, scenario: counts[1].total, load: counts[2].total } };
+    }
+    membership(inventory) { return { plan: pick(inventory.plan, ['id', 'projectId', 'status']), members: inventory.cases.map((x) => pick(x, ['id', 'caseId', 'refId', 'versionId'])).sort((a, b) => a.id.localeCompare(b.id)), other_counts: inventory.other_counts }; }
+    evidenceSnapshot(summary) {
+        const sorted = (items) => [...items].sort((a, b) => digest(a).localeCompare(digest(b)));
+        return { counts: summary.counts, attempts: sorted(summary.attempts), references: sorted(summary.external_defect_references), problems: sorted(summary.problems) };
+    }
+    completionSnapshot(inventory, runId, summary) { return { run_id: runId, membership: this.membership(inventory), cases: inventory.cases.map(executionSnapshot).sort((a, b) => a.execution.id.localeCompare(b.execution.id)), evidence: this.evidenceSnapshot(summary) }; }
+    async executionSummary(inventory, runId) {
+        const counts = { passed: 0, failed: 0, blocked: 0, skipped: 0, not_run: 0 }, problems = [], references = [], attempts = [];
+        for (const item of inventory.cases) {
+            const records = (await this.records(item.caseId)).filter(x => x.plan_id === inventory.plan.id && x.plan_case_id === item.id && x.project_id === item.projectId);
+            const ordered = records.filter(x => x.kind === 'execution').sort((a, b) => (b.recorded_at || 0) - (a.recorded_at || 0));
+            const last = ordered[0];
+            const parsed = last && executionSchema.safeParse(last.result);
+            if (!last || last.run_id !== runId || !parsed?.success || last.definition_hash !== digest(executionDefinition(item))) {
+                counts.not_run++;
+                problems.push({ plan_case_id: item.id, code: 'MISSING_CURRENT_ATTEMPT' });
+                continue;
+            }
+            if (ordered[1]?.recorded_at === last.recorded_at) {
+                counts.not_run++;
+                problems.push({ plan_case_id: item.id, code: 'AMBIGUOUS_ATTEMPT' });
+                continue;
+            }
+            const expected = resultBody(item, parsed.data);
+            if (!fieldsMatch(item, expected)) {
+                counts.not_run++;
+                problems.push({ plan_case_id: item.id, code: 'RESULT_MISMATCH' });
+                continue;
+            }
+            const binding = this.config.workflow.project_bindings.find(x => x.metersphere_project_id === item.projectId);
+            const links = records.filter(x => x.kind === 'mantis_reference' && x.run_id === runId && x.attempt_id === last.attempt_id && x.definition_hash === last.definition_hash && binding?.mantis_project_id === x.mantis_project_id && Number.isSafeInteger(x.issue_id) && x.issue_id > 0);
+            references.push(...links.map(x => ({ ...pick(x, ['issue_id', 'mantis_project_id', 'url', 'relation', 'attempt_id', 'plan_case_id']), record_hash: digest(x) })));
+            if (parsed.data.status === 'failed' && !links.length && !parsed.data.failure_disposition)
+                problems.push({ plan_case_id: item.id, code: 'UNTRIAGED_FAILURE' });
+            counts[parsed.data.status]++;
+            attempts.push({ plan_case_id: item.id, attempt_id: last.attempt_id, comment_id: last.comment_id, actor_id: last.actor_id, record_hash: digest(last) });
+        }
+        const mixed = Object.values(inventory.other_counts).some(x => Number(x) > 0);
+        if (mixed)
+            problems.push({ code: 'MIXED_PLAN' });
+        if (!inventory.cases.length)
+            problems.push({ code: 'EMPTY_PLAN' });
+        return { run_id: runId, counts, attempts, external_defect_references: references, external_reference_count: references.length,
+            all_passed: inventory.cases.length > 0 && counts.passed === inventory.cases.length && !mixed,
+            completion_ready: problems.length === 0, problems, snapshot_consistent: false, proof_of_execution: false };
+    }
+    async report(projectId, reportId) {
+        const reports = await this.all('/test/plan/report/list', { projectId });
+        const meta = reports.find(x => x.id === reportId);
+        ensure(meta && typeof meta.testPlanId === 'string', 'NOT_FOUND_OR_NOT_VISIBLE', '指定项目的报告列表中未找到报告');
+        await this.plan(projectId, meta.testPlanId);
+        const content = object(await this.client.read(`/test/plan/report/db/${segment(reportId)}`), '报告详情');
+        ensure(!content.testPlanReportId || content.testPlanReportId === reportId, 'TARGET_MISMATCH', '报告内容 ID 与目标不符');
+        return { meta, content };
+    }
+    reportView(report) {
+        return { report: pick(report.meta, ['id', 'testPlanId', 'name', 'status', 'creator', 'createTime', 'triggerMode']),
+            content: pick(report.content, ['testPlanReportId', 'name', 'caseCount', 'executeCount', 'passCount', 'summary', 'functionResult']),
+            functional_cases: Array.isArray(report.content.functionAllCases) ? report.content.functionAllCases.map((x) => pick(x, ['id', 'caseId', 'name', 'status', 'results', 'actualResult'])) : null,
+            native_issue_count: Array.isArray(report.content.issueList) ? report.content.issueList.length : null, content_verification: 'partial' };
+    }
+}

package/dist/version.js

@@ -0,0 +1,3 @@
+import { readFileSync } from 'node:fs';
+// 源码与安装包均从根目录清单读取版本，npm version 后无需手改协议或日志。
+export const version = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;

package/dist/workflow/context.js

@@ -0,0 +1,145 @@
+import { array, definitionView, executionSnapshot, pick, segment } from '../adapters/v1-20.js';
+import { ensure } from '../errors.js';
+import { Operations } from './operations.js';
+import { digest } from './tokens.js';
+import { resolveEnabledTools } from './tool-access.js';
+export class Context {
+    ms;
+    enabledTools;
+    constructor(ms) {
+        this.ms = ms;
+        this.enabledTools = resolveEnabledTools(ms.config);
+    }
+    assertToolEnabled(name) { ensure(this.enabledTools.has(name), 'TOOL_DISABLED', '当前工具未启用或已被只读模式禁用'); }
+    ledger(session) { return new Operations(this.ms.config.stateDir, session.namespace, digest(this.ms.config.baseUrl)); }
+    async visible(args) {
+        if (args.project_id)
+            await this.ms.project(args.project_id);
+        if (args.plan_id)
+            await this.ms.plan(args.project_id, args.plan_id);
+        if (args.plan_case_id)
+            await this.ms.planCase(args.project_id, args.plan_id, args.plan_case_id);
+        if (args.case_id)
+            await this.ms.case(args.project_id, args.case_id);
+        if (args.review_id)
+            await this.ms.review(args.project_id, args.review_id);
+        if (args.report_id)
+            await this.ms.report(args.project_id, args.report_id);
+        if (args.node_id)
+            await this.ms.node(args.project_id, args.node_id);
+    }
+    async read(name, input, session) {
+        this.assertToolEnabled(name);
+        const ms = this.ms;
+        if (name === 'get_project_context') {
+            if (!input.project_id) {
+                const spaces = array(await ms.client.read('/workspace/list/userworkspace'), '工作空间');
+                if (!input.workspace_id)
+                    return { user: session.user, workspaces: spaces.map(x => pick(x, ['id', 'name'])), warnings: ['选择 workspace_id 继续发现项目'] };
+                ensure(spaces.some(x => x.id === input.workspace_id), 'NOT_FOUND_OR_NOT_VISIBLE', '当前用户不可见指定工作空间');
+                const result = await ms.query('/project/list', { workspaceId: input.workspace_id }, input, session, x => x.workspaceId === input.workspace_id);
+                return { ...result, items: result.items.map((x) => pick(x, ['id', 'name', 'workspaceId'])), user: session.user };
+            }
+            const project = await ms.project(input.project_id), out = { user: session.user, project: pick(project, ['id', 'name', 'workspaceId']) };
+            if (input.sections.includes('nodes')) {
+                const clean = (nodes) => nodes.map(x => ({ ...pick(x, ['id', 'name', 'level', 'parentId']), children: clean(Array.isArray(x.children) ? x.children : []) }));
+                out.nodes = clean(await ms.nodes(project.id));
+            }
+            if (input.sections.includes('members'))
+                out.members = await ms.members(project.id);
+            if (input.sections.includes('stages'))
+                out.stages = await ms.client.read(`/test/plan/get/stage/option/${segment(project.id)}`);
+            if (input.sections.includes('issue_platform'))
+                out.issue_platform = project.platform ?? null;
+            if (input.sections.includes('bindings'))
+                out.mantis_binding = ms.config.workflow.project_bindings.find(x => x.metersphere_project_id === project.id) ?? null;
+            out.supported_actions_are_not_permissions = true;
+            return out;
+        }
+        await this.visible(input);
+        if (name === 'list_test_cases') {
+            const result = await ms.query('/test/case/list', { projectId: input.project_id, ...(input.node_ids ? { nodeIds: input.node_ids } : {}), ...(input.query ? { name: input.query } : {}) }, input, session, x => x.projectId === input.project_id && x.type === 'functional' && (!input.query || x.name?.includes(input.query)) && (!input.node_ids || input.node_ids.includes(x.nodeId)));
+            return { ...result, items: result.items.map((x) => pick(x, ['id', 'name', 'projectId', 'nodeId', 'priority', 'refId', 'versionId', 'reviewStatus'])) };
+        }
+        if (name === 'get_test_case_context') {
+            const isPlan = !!input.plan_case_id;
+            const state = isPlan ? await ms.planCase(input.project_id, input.plan_id, input.plan_case_id) : await ms.caseEditState(input.project_id, input.case_id);
+            const item = isPlan ? state : state.item, scope = isPlan ? 'case_execution' : 'case_definition';
+            const subject = isPlan ? input.plan_case_id : input.case_id, snapshot = isPlan ? executionSnapshot(item) : state;
+            return { definition: definitionView({ ...item, id: isPlan ? item.caseId : item.id }),
+                ...(isPlan ? { execution: pick(item, ['id', 'caseId', 'planId', 'status', 'executor', 'results', 'actualResult']) } : {}),
+                expected_revision: session.tokens.revision(scope, subject, snapshot), revision_scope: scope,
+                revision_comparison: input.previous_revision ? session.tokens.compare(input.previous_revision, scope, subject, snapshot) : 'not_requested',
+                ...(input.sections.includes('execution_records') ? { execution_records: await ms.records(isPlan ? item.caseId : item.id) } : {}) };
+        }
+        if (name === 'list_test_plans') {
+            const principal = input.executor === 'me' ? session.user.id : input.executor;
+            const result = await ms.query('/test/plan/list', { projectId: input.project_id, ...(input.query ? { name: input.query } : {}) }, input, session, async (x) => {
+                if (x.projectId !== input.project_id || input.query && !x.name?.includes(input.query) || input.statuses && !input.statuses.includes(x.status))
+                    return false;
+                if (!principal)
+                    return true;
+                // 部署的计划列表可能返回 principals=null，不能因此漏掉当前人的计划。
+                x.principals = await ms.principals(x.id);
+                return x.principals.some((p) => p.id === principal);
+            });
+            for (const item of result.items)
+                if (Array.isArray(item.principals))
+                    item.principals = item.principals.map((x) => typeof x === 'string' ? x : pick(x, ['id', 'name']));
+            return { ...result, items: result.items.map((x) => pick(x, ['id', 'projectId', 'name', 'status', 'stage', 'principals', 'testPlanTestCaseCount', 'testPlanApiCaseCount', 'testPlanApiScenarioCount', 'testPlanLoadCaseCount'])),
+                executor_filter_scope: principal ? 'plan_principal_only' : null };
+        }
+        if (name === 'get_case_review_context') {
+            const review = await ms.review(input.project_id, input.review_id);
+            const result = await ms.query('/test/review/case/list', { projectId: input.project_id, reviewId: input.review_id }, input, session, async (x) => {
+                Object.assign(x, await ms.reviewCase(input.project_id, input.review_id, x));
+                return true;
+            });
+            const counts = { passed: 0, failed: 0, pending: 0 };
+            for (const c of result.items) {
+                if (c.reviewStatus === 'Pass')
+                    counts.passed++;
+                else if (c.reviewStatus === 'UnPass')
+                    counts.failed++;
+                else
+                    counts.pending++;
+            }
+            return { review: pick(review, ['id', 'name', 'status', 'projectId']), reviewers: await ms.reviewers(input.review_id), ...result,
+                items: result.items.map((x) => pick(x, ['id', 'caseId', 'name', 'reviewStatus', 'refId', 'versionId'])), counts_in_page: counts,
+                all_passed: !input.cursor && result.source_exhausted && result.items.length > 0 && counts.passed === result.items.length };
+        }
+        if (name === 'get_test_plan_context') {
+            const inventory = await ms.inventory(input.project_id, input.plan_id);
+            const out = { plan: pick(inventory.plan, ['id', 'projectId', 'name', 'status', 'stage', 'description', 'plannedStartTime', 'plannedEndTime']),
+                functional_case_count: inventory.cases.length, other_case_counts: inventory.other_counts,
+                expected_revision: session.tokens.revision('plan_membership', input.plan_id, ms.membership(inventory)), revision_scope: 'plan_membership' };
+            if (input.sections.includes('cases')) {
+                const result = await ms.query('/test/plan/case/list', { projectId: input.project_id, planId: input.plan_id }, input, session, x => x.projectId === input.project_id && x.planId === input.plan_id);
+                out.cases = { ...result, items: result.items.map((x) => pick(x, ['id', 'caseId', 'planId', 'name', 'status', 'priority', 'executor', 'versionId', 'refId'])) };
+            }
+            if (input.sections.includes('reports'))
+                out.reports = (await ms.all('/test/plan/report/list', { projectId: input.project_id })).filter(x => x.testPlanId === input.plan_id).map(x => pick(x, ['id', 'name', 'status', 'createTime', 'creator']));
+            if (input.sections.includes('execution_summary')) {
+                out.execution_summary = await ms.executionSummary(inventory, input.run_id);
+                out.completion_revision = session.tokens.revision('plan_completion', input.plan_id, ms.completionSnapshot(inventory, input.run_id, out.execution_summary));
+                out.execution_summary.pending_operations = await this.ledger(session).pending(input.plan_id);
+                if (out.execution_summary.pending_operations.length)
+                    out.execution_summary.completion_ready = false;
+            }
+            return out;
+        }
+        if (name === 'get_test_report') {
+            const report = await ms.report(input.project_id, input.report_id), out = ms.reportView(report);
+            out.supplement = null;
+            out.supplement_unavailable = true;
+            if (input.operation_id) {
+                const operation = await this.ledger(session).load(input.operation_id);
+                ensure(operation && operation.actor_id === session.user.id && operation.action === 'generate_test_report' && operation.args.project_id === input.project_id && operation.result?.report?.id === input.report_id, 'TARGET_MISMATCH', '操作记录不能与该报告关联');
+                out.supplement = operation.result.execution_summary;
+                out.supplement_unavailable = !out.supplement;
+            }
+            return out;
+        }
+        throw new Error('读取入口不支持该工具');
+    }
+}

package/dist/workflow/contracts.js

@@ -0,0 +1,63 @@
+import { z } from 'zod';
+const id = z.string().trim().min(1).max(200).regex(/^[^\s/\\?#\u0000-\u001f]+$/).describe('从真实上下文获得的字符串 ID');
+const text = z.string().trim().min(1).max(20000).describe('非空正文');
+const name = z.string().trim().min(1).max(255).describe('对象名称，不超过 255 字符');
+const iso = z.iso.datetime({ offset: true }).describe('带时区的 ISO8601 时间');
+const page = { limit: z.number().int().min(1).max(100).optional().describe('本次最多返回条数；省略使用配置默认值'), cursor: text.optional().describe('同一查询返回的续读游标') };
+const common = { operation_id: z.uuid().optional().describe('真实写入必填；重试与恢复保持原 UUID'),
+    dry_run: z.boolean().default(false).describe('只读预览，不验证写入权限'), resume: z.boolean().default(false).describe('恢复原操作，不得改变业务参数'),
+    expected_revision: text.optional().describe('上下文返回的并发前置标识') };
+const project = { project_id: id.describe('MeterSphere 项目 ID') };
+const plan = { ...project, plan_id: id.describe('所属测试计划 ID') };
+const target = { ...plan, plan_case_id: id.describe('计划内用例关联 ID，与用例库 case_id 不同'), run_id: z.uuid().describe('同一执行轮次复用的 UUID'), attempt_id: z.uuid().describe('本次实际执行的 UUID；真正复测才使用新值') };
+const steps = z.array(z.strictObject({ action: text.describe('操作步骤'), expected: text.describe('预期结果') })).min(1).max(100);
+const status = z.enum(['passed', 'failed', 'blocked', 'skipped']);
+export const executionSchema = z.strictObject({ status: status.describe('真实执行结论'), environment: text.describe('实际被测环境'), tested_version: text.optional().describe('实际被测构建或版本'), started_at: iso, finished_at: iso,
+    summary: text.describe('本次执行摘要'), observed: text.describe('实际观察'), reason: text.optional().describe('阻塞或跳过的真实原因'),
+    failure_disposition: z.strictObject({ kind: z.enum(['not_a_product_defect', 'deferred']), reason: text }).optional(),
+    step_results: z.array(z.strictObject({ step_index: z.number().int().positive(), status: z.enum(['passed', 'failed', 'blocked', 'skipped', 'not_run']), observed: text })).max(100).optional(),
+    evidence: z.array(z.strictObject({ kind: z.enum(['text', 'url']), value: text }).refine(x => x.kind !== 'url' || /^https:\/\//.test(x.value), '证据 URL 须使用 HTTPS')).min(1).max(20),
+}).refine(x => Date.parse(x.finished_at) >= Date.parse(x.started_at), '结束时间不得早于开始时间')
+    .refine(x => !['blocked', 'skipped'].includes(x.status) || !!x.reason, '阻塞或跳过须填写原因');
+const changes = z.strictObject({ name: name.optional(), node_id: id.optional(), priority: z.enum(['P0', 'P1', 'P2', 'P3']).optional(),
+    prerequisite: z.string().max(20000).optional(), steps: steps.optional(), step_description: text.optional(), expected_result: text.optional(),
+    tags: z.array(z.string().max(100)).max(50).optional(), remark: z.string().max(20000).optional() })
+    .refine(x => Object.keys(x).length > 0, '至少修改一个字段').refine(x => !x.steps || !x.step_description && !x.expected_result, 'STEP 与 TEXT 字段不能混用');
+export const schemas = {
+    get_project_context: z.strictObject({ workspace_id: id.optional(), project_id: id.optional(), sections: z.array(z.enum(['nodes', 'members', 'stages', 'issue_platform', 'bindings'])).default([]), ...page }),
+    list_test_cases: z.strictObject({ ...project, node_ids: z.array(id).max(50).optional(), query: text.optional(), ...page }),
+    create_case_module: z.strictObject({ ...common, ...project,
+        name: z.string().trim().min(1).max(100).regex(/^[^/\\\u0000-\u001f]+$/).describe('功能用例模块名称，不超过 100 字符，不含路径分隔符'),
+        parent_id: id.nullable().optional().describe('父模块真实 ID；省略或 null 创建一级模块，传入 ID 创建子模块，最多 8 层') }),
+    get_test_case_context: z.strictObject({ ...project, case_id: id.optional(), plan_id: id.optional(), plan_case_id: id.optional(),
+        sections: z.array(z.enum(['execution_records'])).default([]), previous_revision: text.optional() })
+        .refine(x => !!x.case_id !== !!x.plan_case_id && (!!x.plan_case_id === !!x.plan_id), '传 case_id 或同时传 plan_id、plan_case_id'),
+    create_test_case: z.strictObject({ ...common, ...project, node_id: id, name, priority: z.enum(['P0', 'P1', 'P2', 'P3']).default('P3'), prerequisite: z.string().max(20000).default(''), steps,
+        tags: z.array(z.string().max(100)).max(50).default([]).describe('自定义标签；自动补充并去重 AI 标签，合并后最多 50 个'),
+        remark: z.string().max(20000).default('').describe('用户备注；不自动追加操作标记') }),
+    update_test_case: z.strictObject({ ...common, ...project, case_id: id, changes }),
+    create_case_review: z.strictObject({ ...common, ...project, name, case_ids: z.array(id).min(1).max(50), reviewer_ids: z.array(id).min(1).max(50), description: z.string().max(20000).default(''), ends_at: iso.optional() }),
+    get_case_review_context: z.strictObject({ ...project, review_id: id, ...page }),
+    list_test_plans: z.strictObject({ ...project, query: text.optional(), executor: id.optional(), statuses: z.array(z.enum(['Prepare', 'Underway', 'Completed', 'Finished', 'Archived'])).optional(), ...page }),
+    get_test_plan_context: z.strictObject({ ...plan, sections: z.array(z.enum(['cases', 'reports', 'execution_summary'])).default(['cases']), run_id: z.uuid().optional(), ...page })
+        .refine(x => !x.sections.includes('execution_summary') || !!x.run_id, '执行汇总须指定 run_id'),
+    create_test_plan: z.strictObject({ ...common, ...project, name, stage: text, principal_ids: z.array(id).min(1).max(50), starts_at: iso, ends_at: iso, description: z.string().max(20000).default('') })
+        .refine(x => Date.parse(x.ends_at) >= Date.parse(x.starts_at), '计划结束时间不得早于开始时间'),
+    add_cases_to_plan: z.strictObject({ ...common, ...plan, case_ids: z.array(id).min(1).max(50) }),
+    record_case_result: z.strictObject({ ...common, ...target, result: executionSchema }),
+    link_mantis_issue: z.strictObject({ ...common, ...target, mantis_project_id: z.number().int().positive(), issue_id: z.number().int().positive(), relation: z.enum(['found_in', 'verified_in']), reason: text }),
+    complete_test_plan: z.strictObject({ ...common, ...plan, run_id: z.uuid(), summary: text }),
+    generate_test_report: z.strictObject({ ...common, ...plan, run_id: z.uuid() }),
+    get_test_report: z.strictObject({ ...project, report_id: id, operation_id: z.uuid().optional() }),
+    get_workflow_operation: z.strictObject({ operation_id: z.uuid() }),
+};
+export const toolNames = Object.keys(schemas);
+export const readTools = new Set(['get_project_context', 'list_test_cases', 'get_test_case_context', 'get_case_review_context', 'list_test_plans', 'get_test_plan_context', 'get_test_report', 'get_workflow_operation']);
+export const resultSchema = z.object({ schema_version: z.literal(1), error: z.strictObject({ code: z.string(), message: z.string(), system_code: z.string().optional() }).optional() }).catchall(z.unknown());
+const dataObject = z.record(z.string(), z.unknown());
+export const writeResultSchema = z.object({
+    schema_version: z.literal(1), action: z.string(), operation_id: z.uuid().nullable(),
+    outcome: z.enum(['preview', 'succeeded', 'partial_success', 'unknown', 'conflict', 'rejected', 'in_progress']),
+    subject: dataObject, result: dataObject.nullable(), steps: z.array(z.object({ name: z.string(), state: z.enum(['not_started', 'in_flight', 'succeeded', 'rejected', 'unknown']), error: dataObject.optional() })),
+    verification: dataObject, recovery: dataObject, warnings: z.array(z.string()), error: resultSchema.shape.error,
+});