@youcloud/mantis-mcp 1.0.3 → 1.0.5

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # 更新记录
 
+## [1.0.5] - 2026-10-19
+
+- 用户引用兼容无前导零的十进制编号字符串，统一为数字后指派、筛选与恢复；补充明确的格式错误提示，继续拒绝含糊类型和不安全整数。
+- 缺陷上下文补齐备注附件索引、所属备注与去重，避免顶层附件为空时遗漏分析材料。
+
+## [1.0.4] - 2026-10-19
+
+- 修复 Windows 下操作账本目录同步失败导致所有写工具及操作核查不可用的问题；保留文件同步与替换失败的阻断行为，并清理失败的临时文件。
+- 本地异常诊断保留已知系统错误码，不暴露路径、凭据或底层异常正文。
+- 增加跨平台账本、`submit_fix` / `add_note` 写入与恢复回归，覆盖 Windows 故障模拟及真实文件错误。
+
 ## [1.0.1] - 2026-10-18
 
 - `MANTIS_BASE_URL` 未设置或为空白时默认使用 `https://mantis.umlife.net`，仍可显式指定其他部署地址。

package/README.md

@@ -1,21 +1,21 @@
 # Mantis MCP
 
-内部研发团队使用的 MantisBT MCP 服务，通过 stdio 为 Coding Agent 提供缺陷查询、修复登记、附件上传和可恢复的工作流操作。
+内部研发团队使用的 MantisBT MCP 服务，通过 stdio 为 Coding Agent 提供缺陷创建、查询、分配、修复、关闭等全生命周期管理和可恢复操作。
 
-项目与问题反馈：[内部 GitLab](https://git.umlife.net/ai-tools/mantis-mcp)。npm 包：[@youcloud/mantis-mcp](https://www.npmjs.com/package/@youcloud/mantis-mcp)。
+项目与问题反馈：[内部 GitLab](https://git.umlife.net/ai-tools/mantis-mcp/-/work_items)。npm 包：[@youcloud/mantis-mcp](https://www.npmjs.com/package/@youcloud/mantis-mcp)。
 
-## 开始使用
+## 三分钟上手
 
-需要 Node.js ≥ 22（至少 22.12），并准备 MantisBT API 令牌（在“我的账号 → 个人资料 → API令牌”下创建）。
+需要 Node.js ≥ 22（至少 22.12），并准备 [MantisBT](https://mantis.umlife.net) API 令牌（在“我的账号 → 个人资料 → API令牌”下创建）。
 
-### CodeX
+#### CodeX
 ```bash
 codex mcp add mantis \
   --env MANTIS_API_KEY="$MANTIS_API_KEY" \
   -- npx -y @youcloud/mantis-mcp@latest
 ```
 
-### Claude Code
+#### Claude Code
 ```bash
 # Claude Code 不加 --scope user 时，默认仅在添加时所在的项目中生效
 claude mcp add --scope user mantis \
@@ -23,12 +23,12 @@ claude mcp add --scope user mantis \
   -- npx -y @youcloud/mantis-mcp@latest
 ```
 
-### 全局安装
+#### 全局安装
 ```bash
 npm install -g @youcloud/mantis-mcp
 ```
 
-### 自定义配置
+#### 自定义配置
 
 1. 在 Mantis 生成个人 API Key，通过 `MANTIS_API_KEY` 传入；默认连接内部 Mantis，详见[服务配置](docs/configuration.md)。
 2. 按[客户端接入](docs/clients.md)配置 Codex、Claude Code、Cursor 或 Trae。

package/dist/services/issues.js

@@ -24,11 +24,18 @@ export class Issues {
     }
 }
 export function visibleCollection(issue, key, emptyArraysOmitted) {
-    if (Array.isArray(issue[key]))
-        return issue[key];
-    if (!(key in issue) && emptyArraysOmitted && ['attachments', 'notes', 'relationships'].includes(key))
-        return [];
-    return undefined;
+    const items = Array.isArray(issue[key]) ? issue[key]
+        : !(key in issue) && emptyArraysOmitted && ['attachments', 'notes', 'relationships'].includes(key) ? [] : undefined;
+    if (key !== 'attachments' || !items)
+        return items;
+    // REST 将备注附件放在 notes[].attachments；只合并当前响应已可见的附件，不修改原始事实快照。
+    const attachments = new Map(items.map(item => [item.id, item]));
+    for (const note of Array.isArray(issue.notes) ? issue.notes : []) {
+        for (const attachment of Array.isArray(note.attachments) ? note.attachments : []) {
+            attachments.set(attachment.id, { ...attachments.get(attachment.id), ...attachment, note_id: note.id });
+        }
+    }
+    return [...attachments.values()];
 }
 export function facts(issue, baseUrl) {
     const keys = ['id', 'summary', 'project', 'category', 'priority', 'severity', 'status', 'resolution', 'version', 'fixed_in_version', 'target_version', 'updated_at'];

package/dist/workflow/context.js

@@ -168,9 +168,11 @@ export class Context {
                 let item;
                 if (section === 'notes')
                     item = { id: raw.id, reporter: minimalUser(raw.reporter), text: raw.text, view_state: raw.view_state,
+                        ...(Array.isArray(raw.attachments) && raw.attachments.length ? { attachment_ids: raw.attachments.map((a) => a.id) } : {}),
                         updated_at: raw.updated_at, view_url: `${session.baseUrl}/view.php?id=${issue.id}#bugnote${raw.id}` };
                 else if (section === 'attachments')
                     item = { id: raw.id, filename: raw.file_name ?? raw.filename, size: raw.size, content_type: raw.content_type,
+                        ...(raw.note_id !== undefined ? { note_id: raw.note_id } : {}),
                         download_url: `${session.baseUrl}/file_download.php?file_id=${raw.id}&type=bug`, view_url: output.issue.view_url };
                 else if (section === 'monitors')
                     item = minimalUser(raw);

package/dist/workflow/contracts.js

@@ -1,9 +1,17 @@
 import { z } from 'zod';
+import { getSystemErrorMap } from 'node:util';
 import { RestError } from '../client.js';
 import { ConnectionConfigError } from '../connection-config.js';
+const systemErrorCodes = new Set([...getSystemErrorMap().values()].map(([name]) => name));
 export const id = z.number().int().positive().describe('正整数编号');
 export const text = z.string().refine(v => v.trim().length > 0, '不可为空白').describe('非空正文');
-const ref = z.union([z.literal('me'), id]).describe('当前用户 me 或明确的用户编号');
+const refError = '用户引用须为 "me"、正整数用户编号或其十进制字符串（无前导零，最大 9007199254740991）；用户名请先用 get_project_context 查询编号';
+// 仅兼容明确的十进制编号，避免数字强转把布尔值、数组或指数写法当成用户。
+const userId = z.number().int({ error: refError }).positive({ error: refError });
+const userIdString = z.string().regex(/^[1-9][0-9]*$/, refError)
+    .refine(value => Number.isSafeInteger(Number(value)), refError).transform(Number);
+const ref = z.union([z.literal('me'), userId, userIdString], { error: refError })
+    .describe('当前用户 "me"、正整数用户编号或无前导零的十进制编号字符串；不接受用户名');
 const iso = z.iso.datetime({ offset: true }).describe('含时区的 ISO8601 时间');
 const evidence = z.array(z.strictObject({ kind: z.enum(['url', 'text']), value: text }));
 const environment = { environment: text.optional(), version_id: id.optional() };
@@ -87,7 +95,10 @@ export function problem(error) {
                 : error.status === 403 || error.status === 401 ? 'MANTIS_FORBIDDEN'
                     : error.status === 404 ? 'NOT_FOUND_OR_NOT_VISIBLE' : error.status === 412 ? 'REVISION_CONFLICT'
                         : !error.definiteRejection ? error.method === 'GET' ? 'SERVICE_UNAVAILABLE' : 'WRITE_OUTCOME_UNKNOWN' : 'MANTIS_REJECTED', message: error.message };
-    return { code: 'SERVICE_UNAVAILABLE', message: '本地服务或读取不可用；未包含敏感错误正文' };
+    // 只展示 Node.js 已知的系统错误码，不回显任意 code、路径或底层异常正文。
+    const code = error instanceof Error ? error.code : undefined;
+    const diagnostic = typeof code === 'string' && systemErrorCodes.has(code) ? `（系统错误：${code}）` : '';
+    return { code: 'SERVICE_UNAVAILABLE', message: `本地服务或读取不可用${diagnostic}；未包含敏感错误正文` };
 }
 const record = z.record(z.string(), z.unknown());
 export const stepSchema = z.strictObject({ name: z.string(), state: z.enum(['not_started', 'in_flight', 'succeeded', 'failed', 'unknown']),

package/dist/workflow/operations.js

@@ -35,20 +35,23 @@ export class Operations {
         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();
+                await handle.writeFile(JSON.stringify(record));
+                await handle.sync();
             }
             finally {
-                await directory.close();
+                await handle.close();
+            }
+            await rename(temp, join(this.dir, `${record.operation_id}.json`));
+            // Windows 不支持此目录同步方式；文件写入、同步和替换失败仍须阻断后续业务写入。
+            if (process.platform !== 'win32') {
+                const directory = await open(this.dir, 'r');
+                try {
+                    await directory.sync();
+                }
+                finally {
+                    await directory.close();
+                }
             }
         }
         finally {

package/docs/cookbook.md

@@ -58,6 +58,8 @@
 
 ## 写入公共参数与生命周期
 
+用户引用 `assignee`（指派、受理、查询）和 `reporter`（查询）接受 `"me"`、正整数编号或无前导零的十进制编号字符串，例如 `5` 与 `"5"` 等价。编号不得超过 `9007199254740991`；不接受空白、布尔值、数组、指数写法或用户名。按姓名或登录名操作时，先用 `get_project_context` 的 `members` 区块和 `member_query` 确认用户编号，再传入引用。
+
 | 参数 | 规则 |
 |---|---|
 | `operation_id` | 每个新动作独立 UUID；真实写入必填，同次核查和恢复保持不变 |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@youcloud/mantis-mcp",
-  "version": "1.0.3",
-  "description": "面向研发工作流的 MantisBT MCP 服务，支持缺陷查询、修复登记、附件和可恢复操作",
+  "version": "1.0.5",
+  "description": "面向研发工作流的 MantisBT MCP 服务，支持缺陷创建、查询、分配、修复、关闭等全生命周期管理和可恢复操作",
   "license": "MIT",
   "homepage": "https://git.umlife.net/ai-tools/mantis-mcp",
   "bugs": {