@youcloud/mantis-mcp 1.0.2 → 1.0.4

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # 更新记录
 
+## [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

@@ -2,20 +2,20 @@
 
 内部研发团队使用的 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。
@@ -38,16 +38,27 @@ npm install -g @youcloud/mantis-mcp
 
 修改已有对象前须读取最新 context，真实写入使用独立 `operation_id`。遇到 `partial_success/unknown` 时按原编号核查，不能直接重发。
 
+## 日常使用场景
+
+- 目前分配给我的缺陷有哪些？
+- 获取一下问题 #22474 的详细内容
+- 问题 #22474 的状态是什么？
+- 问题 #18133 是由于样式加载异常导致，已修复且自测通过，请把状态调整已修复
+- 显示创意管家项目中所有未解决的问题
+- ...
+
+
+
 ## 文档
 
 | 文档 | 内容 |
 |---|---|
-| [客户端接入](docs/clients.md) | 安装配置、凭据传入与连接排障 |
-| [服务配置](docs/configuration.md) | 环境变量、动作映射与部署边界 |
-| [调用手册](docs/cookbook.md) | 工具、常用场景及写入恢复 |
+| [客户端接入](https://git.umlife.net/ai-tools/mantis-mcp/-/blob/main/docs/clients.md) | 安装配置、凭据传入与连接排障 |
+| [服务配置](https://git.umlife.net/ai-tools/mantis-mcp/-/blob/main/docs/configuration.md) | 环境变量、动作映射与部署边界 |
+| [调用手册](https://git.umlife.net/ai-tools/mantis-mcp/-/blob/main/docs/cookbook.md) | 工具、常用场景及写入恢复 |
 | [项目设计](https://git.umlife.net/ai-tools/mantis-mcp/-/blob/main/docs/design.md) | 架构、契约、状态持久化与安全边界 |
 | [开发指南](https://git.umlife.net/ai-tools/mantis-mcp/-/blob/main/CONTRIBUTING.md) | 本地开发、验证和文档维护 |
 | [发布流程](https://git.umlife.net/ai-tools/mantis-mcp/-/blob/main/docs/releasing.md) | GitLab 与 npm 发布检查 |
-| [更新记录](CHANGELOG.md) | 版本变化 |
+| [更新记录](https://git.umlife.net/ai-tools/mantis-mcp/-/blob/main/CHANGELOG.md) | 版本变化 |
 
 采用 [MIT 许可证](LICENSE)。

package/dist/workflow/contracts.js

@@ -1,6 +1,8 @@
 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 或明确的用户编号');
@@ -87,7 +89,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@youcloud/mantis-mcp",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "面向研发工作流的 MantisBT MCP 服务，支持缺陷查询、修复登记、附件和可恢复操作",
   "license": "MIT",
   "homepage": "https://git.umlife.net/ai-tools/mantis-mcp",