@ai-zen/agents-host 0.1.0-alpha.2 → 0.1.0-alpha.3

package/dist/config.d.ts

@@ -92,8 +92,9 @@ export interface HostSettings {
  * 读 `<dataRoot>/host.json`。
  *
  * 三种情况分开：文件不在 → 空设置（这一档没说话，静默）；读不出来 / 不是 JSON / 不是对象 →
- * 就是坏文件，恢复出厂：当空设置用（默认端口、默认语言）、写回一份合法的 `{}`、回调一次
- * （D32：坏了就恢复出厂，下次启动不再遇到同一个坏文件）；`port` 在但不是可用端口 →
+ * 就是坏文件，恢复出厂：先把坏文件改名留档为 `host.json.broken`、再写回一份合法的 `{}`、
+ * 再回调一次（D32：坏了就恢复出厂，下次启动不再遇到同一个坏文件；留档是数据，不是兜底 ——
+ * 用户手写的端口设置得能查回来）；`port` 在但不是可用端口 →
  * `config_invalid`（裁定 R67：显式给出的非法值报错，不静默回落）。
  */
 export declare function readHostSettings(paths: HostPaths, onRecovered?: ConfigRecoveredHandler): Promise<HostSettings>;

package/dist/config.js

@@ -1,4 +1,4 @@
-import { readFile, writeFile } from "node:fs/promises";
+import { access, readFile, rename, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { HostError } from "./wire/errors.js";
@@ -120,8 +120,9 @@ function invalidPort(field, value, source) {
  * 读 `<dataRoot>/host.json`。
  *
  * 三种情况分开：文件不在 → 空设置（这一档没说话，静默）；读不出来 / 不是 JSON / 不是对象 →
- * 就是坏文件，恢复出厂：当空设置用（默认端口、默认语言）、写回一份合法的 `{}`、回调一次
- * （D32：坏了就恢复出厂，下次启动不再遇到同一个坏文件）；`port` 在但不是可用端口 →
+ * 就是坏文件，恢复出厂：先把坏文件改名留档为 `host.json.broken`、再写回一份合法的 `{}`、
+ * 再回调一次（D32：坏了就恢复出厂，下次启动不再遇到同一个坏文件；留档是数据，不是兜底 ——
+ * 用户手写的端口设置得能查回来）；`port` 在但不是可用端口 →
  * `config_invalid`（裁定 R67：显式给出的非法值报错，不静默回落）。
  */
 export async function readHostSettings(paths, onRecovered) {
@@ -154,13 +155,38 @@ export async function readHostSettings(paths, onRecovered) {
     return { port };
 }
 /**
- * 坏掉之后恢复出厂：写回一份合法的 `{}`（＝默认端口、默认语言），再回调一次。
+ * 坏掉之后恢复出厂：先把坏文件留档，再写回一份合法的 `{}`（＝默认端口、默认语言），再回调一次。
  */
 async function recoverHostSettings(paths, onRecovered) {
+    await archiveBroken(paths.hostConfigFile);
     await writeFile(paths.hostConfigFile, "{}\n", "utf8");
     await onRecovered?.(paths.hostConfigFile);
     return {};
 }
+/**
+ * 把坏掉的设置文件改名留档为 `host.json.broken`。
+ *
+ * 与 SDK 的 `ConfigManager.archiveBroken()` 同一条规则（三个配置文件同一口径）：同名残骸
+ * 已经在就带上时间戳（同一毫秒再撞上就补序号），不覆盖上一份残骸。
+ */
+async function archiveBroken(path) {
+    const base = `${path}.broken`;
+    let target = base;
+    for (let index = 0; await exists(target); index += 1) {
+        target = index === 0 ? `${base}.${Date.now()}` : `${base}.${Date.now()}-${index}`;
+    }
+    await rename(path, target);
+}
+/** 这个路径在不在（`access` 不抛就是在） */
+async function exists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 function isMissingFile(error) {
     return (typeof error === "object" &&
         error !== null &&

package/dist/services/DiscoveryService.d.ts

@@ -2,9 +2,16 @@
  * 能力发现服务：把「这个项目现在能用哪些 MCP / Skill / 工具 / 子 Agent」摊成分层清单。
  *
  * 对应能力编号：F-G1（MCP 5 层链，可编辑的只有 2 个作用域）、F-G2（Skill 4 层、工具与子 Agent
- * 各 2 层，只发现真实存在的目录，离项目越近越优先）、F-F6（坏文件要能看见、能修）、
+ * 各 2 层，只发现真实存在的目录，离项目越近越优先）、F-F6（坏文件按层分两种处置，见下）、
  * L9（MCP 的 5 层链）、R54（5 层链与各能力目录由本服务算好交给 ScopeRegistry）。
  *
+ * **F-F6 里「坏文件」的那条口径不是一句话，按文件在哪分**：用户级那份
+ * （`<数据根>/mcp.json`）坏了由 SDK 恢复出厂并留残骸（PRD D32），本服务因此看到的是一个
+ * 好文件（除非文件是运行期才坏的，那时下一次启动才恢复）；项目侧
+ * （`<cwd>/.mcp.json`、`<cwd>/.ai-zen/mcp.json`、`<cwd>/.agents/mcp.json`）与
+ * `~/.agents/mcp.json` 坏了仍然是看得见的 `broken` 状态、能修 —— 那些文件在用户的仓库里，
+ * 恢复出厂等于改人家的 git 内容。
+ *
  * 三件事分开：
  *
  *   1. **路径**（{@link DiscoveryService.scopeAbilityPaths} 等）：只有「按 cwd 推出各能力应该去
@@ -12,7 +19,8 @@
  *      `createWorkspaceScopeFactory`）拿的就是这些路径。
  *   2. **读**（{@link DiscoveryService.discover}）：把每一层的 `missing | ok | broken` 与条目
  *      报出来。`missing` 与 `broken` 必须分开（F-F6）：以前两者都当空配置，一保存就把用户的
- *      文件覆盖掉了。
+ *      文件覆盖掉了；`broken` 在项目侧与 `~/.agents` 各层是「看得见、能修」，用户级那层由
+ *      SDK 恢复出厂（D32）。
  *   3. **写**（{@link DiscoveryService.writeMcpEntry} / {@link DiscoveryService.deleteMcpEntry}）：
  *      只写 MCP 的两个可编辑作用域，一次只动一条；写回时保留这一版不认识的字段与 `oauth`
  *      （F-F6），其中 `oauth.clientSecret` 省略就按磁盘原文保留（F-F2：读出去的是掩码，

package/dist/services/DiscoveryService.js

@@ -2,9 +2,16 @@
  * 能力发现服务：把「这个项目现在能用哪些 MCP / Skill / 工具 / 子 Agent」摊成分层清单。
  *
  * 对应能力编号：F-G1（MCP 5 层链，可编辑的只有 2 个作用域）、F-G2（Skill 4 层、工具与子 Agent
- * 各 2 层，只发现真实存在的目录，离项目越近越优先）、F-F6（坏文件要能看见、能修）、
+ * 各 2 层，只发现真实存在的目录，离项目越近越优先）、F-F6（坏文件按层分两种处置，见下）、
  * L9（MCP 的 5 层链）、R54（5 层链与各能力目录由本服务算好交给 ScopeRegistry）。
  *
+ * **F-F6 里「坏文件」的那条口径不是一句话，按文件在哪分**：用户级那份
+ * （`<数据根>/mcp.json`）坏了由 SDK 恢复出厂并留残骸（PRD D32），本服务因此看到的是一个
+ * 好文件（除非文件是运行期才坏的，那时下一次启动才恢复）；项目侧
+ * （`<cwd>/.mcp.json`、`<cwd>/.ai-zen/mcp.json`、`<cwd>/.agents/mcp.json`）与
+ * `~/.agents/mcp.json` 坏了仍然是看得见的 `broken` 状态、能修 —— 那些文件在用户的仓库里，
+ * 恢复出厂等于改人家的 git 内容。
+ *
  * 三件事分开：
  *
  *   1. **路径**（{@link DiscoveryService.scopeAbilityPaths} 等）：只有「按 cwd 推出各能力应该去
@@ -12,7 +19,8 @@
  *      `createWorkspaceScopeFactory`）拿的就是这些路径。
  *   2. **读**（{@link DiscoveryService.discover}）：把每一层的 `missing | ok | broken` 与条目
  *      报出来。`missing` 与 `broken` 必须分开（F-F6）：以前两者都当空配置，一保存就把用户的
- *      文件覆盖掉了。
+ *      文件覆盖掉了；`broken` 在项目侧与 `~/.agents` 各层是「看得见、能修」，用户级那层由
+ *      SDK 恢复出厂（D32）。
  *   3. **写**（{@link DiscoveryService.writeMcpEntry} / {@link DiscoveryService.deleteMcpEntry}）：
  *      只写 MCP 的两个可编辑作用域，一次只动一条；写回时保留这一版不认识的字段与 `oauth`
  *      （F-F6），其中 `oauth.clientSecret` 省略就按磁盘原文保留（F-F2：读出去的是掩码，

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-zen/agents-host",
-  "version": "0.1.0-alpha.2",
+  "version": "0.1.0-alpha.3",
   "description": "AI-Zen Agents Host — session/workspace service shared by CLI and Desktop",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -40,7 +40,7 @@
   "license": "MIT",
   "dependencies": {
     "@ai-zen/agents-core": "^4.6.0-alpha.0",
-    "@ai-zen/agents-sdk": "^1.2.0-alpha.1",
+    "@ai-zen/agents-sdk": "^1.2.0-alpha.2",
     "ws": "^8.22.2"
   },
   "devDependencies": {