@whispering233/ai-editor-server 0.0.1

package/dist/routes/delta.js

@@ -0,0 +1,144 @@
+// Delta 路由（S5.3）：POST /api/v1/delta（追加）/ GET /node/:nodeId（按节点查询）/ POST /compute（状态计算）
+//
+// 契约来源：doc/api/endpoints.md 第 395-510 行（Delta 变更追踪）、决策 9（computeState 累积规则）、
+// 决策 12 修订（可见性联动）、S13.3 收紧（变更目标仅实体类型——大纲节点不可作为变更目标，
+//   历史 outline_node 目标数据保留展示，创建路径拒绝）。
+// 错误映射（对照 endpoints.md 错误码）：
+//   参数校验失败 → 400 VALIDATION_ERROR（zod 抛错由 errorHandler 统一映射，含 fields；
+//     per-op 必填字段（endpoints.md 第 407-418 行）因 op 而异、zod 无法表达，路由层补校验
+//     → HttpError 400 VALIDATION_ERROR，与 entity.ts validateDataByType 同思路；
+//     S13.3 target_type 白名单校验同此 400——schema 层 target_type 为宽松 z.string()，
+//     收紧在路由层（shared schema 不动，同 S12.1 节点 data 校验模式））
+//   触发节点不存在或已软删 → 404 OUTLINE_NODE_NOT_FOUND（POST /delta 与 /delta/compute 路由层前置校验；
+//     POST /delta 契约虽未定义该错误码，但 db 层 insertDelta 不校验节点（delta.ts 注释：缺失节点记录
+//     因可见性规则永久不可见），路由层拦截防死记录——oracle 建议）
+//   目标实体不存在或已软删 → 404 ENTITY_NOT_FOUND（POST /delta/compute）
+import { Hono } from "hono";
+import { computeState, findOutlineNode, getEntity, insertDelta, listDeltasByNode, readOutlineFile } from "@whispering233/ai-editor-db";
+import { ENTITY_TYPES, mapRowToDelta } from "@whispering233/ai-editor-shared";
+import { deltaComputeReqSchema, deltaCreateReqSchema } from "@whispering233/ai-editor-shared/schemas";
+import { HttpError, ok } from "../middleware/error.js";
+import { requireCurrentProject } from "../middleware/project.js";
+/** Delta 路由（挂载于 /api/v1/delta，index.ts） */
+export const deltaRoutes = new Hono();
+/**
+ * 前置校验大纲节点存在且未软删（oracle 建议，防死记录）：
+ * db 层 insertDelta / computeState 均不校验触发节点存在性（契约未定义该错误码，delta.ts 注释），
+ * 缺失节点记录会因可见性规则（决策 12 修订：触发节点缺失视同不可见）永久不可见，
+ * 故路由层拦截并映射 404 OUTLINE_NODE_NOT_FOUND；computeState 的 getOutlinePathIds
+ * 对缺失节点抛错（视为调用方 bug），同样由本校验先行兜底。
+ */
+function assertOutlineNode(project, nodeId) {
+    const tree = readOutlineFile(project.root);
+    const node = findOutlineNode(tree, nodeId);
+    if (node === undefined || node.deleted === true) {
+        throw new HttpError(404, "OUTLINE_NODE_NOT_FOUND", `大纲节点不存在: ${nodeId}`);
+    }
+}
+/**
+ * per-op 必填字段校验（endpoints.md 第 407-418 行）：
+ *   op=set → to 必填；op=update → from+to 必填；op=add → value 必填；op=remove → value 必填。
+ * deltaChangeSchema 的字段均 optional——必填语义因 op 而异，schema 层无法表达，
+ * 由路由层按 op 分派校验（与 entity.ts validateDataByType「schema 之外按类型精校验」同思路）。
+ * 不满足 → 400 VALIDATION_ERROR（message 注明 changes 下标与缺失字段）。
+ */
+function validateChangesByOp(changes) {
+    for (let i = 0; i < changes.length; i++) {
+        const { op, from, to, value } = changes[i];
+        const missing = [];
+        switch (op) {
+            case "set":
+                if (to === undefined)
+                    missing.push("to");
+                break;
+            case "update":
+                if (from === undefined)
+                    missing.push("from");
+                if (to === undefined)
+                    missing.push("to");
+                break;
+            case "add":
+                if (value === undefined)
+                    missing.push("value");
+                break;
+            case "remove":
+                if (value === undefined)
+                    missing.push("value");
+                break;
+        }
+        if (missing.length > 0) {
+            throw new HttpError(400, "VALIDATION_ERROR", `changes[${i}] op=${op} 缺少必填字段: ${missing.join("/")}`);
+        }
+    }
+}
+/**
+ * 变更目标类型白名单校验（S13.3 收紧：仅实体类型 character/setting/location/hook——大纲节点代表的
+ * 故事导致实体发生变更，节点结构化信息不应出现在变更记录中；历史 outline_node 目标数据保留展示，
+ * 仅创建路径拒绝）。schema 层 target_type 为宽松 z.string()（shared 不动），收紧在路由层
+ * （与 S12.1 节点 data 按层级校验同模式）。不通过 → 400 VALIDATION_ERROR（参照 entity.ts parseTypeParam 错误风格）。
+ */
+function assertDeltaTargetType(targetType) {
+    if (!ENTITY_TYPES.includes(targetType)) {
+        throw new HttpError(400, "VALIDATION_ERROR", `非法变更目标类型: ${targetType}（变更目标仅限实体类型: ${ENTITY_TYPES.join("/")}）`);
+    }
+}
+// POST /api/v1/delta —— 追加属性变更（201；order 服务端全局单调生成）
+// 校验顺序（oracle 建议）：schema → target_type 白名单（400，S13.3 请求形状校验，无 DB 读）→
+//   触发节点存在性（404）→ per-op 必填（400）→ insert
+deltaRoutes.post("/", async (c) => {
+    const project = requireCurrentProject();
+    const raw = await c.req.json().catch(() => null);
+    const parsed = deltaCreateReqSchema.safeParse(raw);
+    if (!parsed.success) {
+        throw parsed.error; // → 400 VALIDATION_ERROR（含 fields）
+    }
+    const { node_id, target_type, target_id, changes, description } = parsed.data;
+    assertDeltaTargetType(target_type); // S13.3：变更目标仅实体类型（shared schema 不动，路由层收紧）
+    assertOutlineNode(project, node_id); // 触发节点必须存在且未软删（防死记录）
+    validateChangesByOp(changes); // per-op 必填字段（endpoints.md 第 407-418 行）
+    const row = insertDelta(project.db, {
+        nodeId: node_id,
+        targetType: target_type,
+        targetId: target_id,
+        changes,
+        description,
+    });
+    return c.json(ok({ id: row.id, applied: mapRowToDelta(row) }), 201);
+});
+// GET /api/v1/delta/node/:nodeId —— 按触发节点查询（200）
+// 契约未定义该端点 404（endpoints.md 第 436-462 行）：节点缺失/软删 → 空数组（listDeltasByNode
+// 内置可见性三态过滤，触发节点缺失视同不可见），不 404。
+deltaRoutes.get("/node/:nodeId", (c) => {
+    const project = requireCurrentProject();
+    const nodeId = c.req.param("nodeId");
+    const deltas = listDeltasByNode(project.db, nodeId, project.root);
+    return c.json(ok({ nodeId, deltas }));
+});
+// POST /api/v1/delta/compute —— 累积状态计算（决策 9，endpoints.md 第 464-510 行）
+// 校验顺序（任务规格）：schema → at_node_id 存在性（404 OUTLINE_NODE_NOT_FOUND，
+//   computeState 的 getOutlinePathIds 对缺失节点抛错——路由层先拦截）→ 目标实体存在性
+//   （404 ENTITY_NOT_FOUND；computeState 对缺失/软删实体返回 null）→ computeState → 200
+deltaRoutes.post("/compute", async (c) => {
+    const project = requireCurrentProject();
+    const raw = await c.req.json().catch(() => null);
+    const parsed = deltaComputeReqSchema.safeParse(raw);
+    if (!parsed.success) {
+        throw parsed.error; // → 400 VALIDATION_ERROR（含 fields）
+    }
+    const { target_type, target_id, at_node_id } = parsed.data;
+    assertOutlineNode(project, at_node_id);
+    if (getEntity(project.db, target_id) === null) {
+        throw new HttpError(404, "ENTITY_NOT_FOUND", `实体不存在: ${target_id}`);
+    }
+    const result = computeState(project.db, project.root, {
+        targetType: target_type,
+        targetId: target_id,
+        atNodeId: at_node_id,
+    });
+    if (result === null) {
+        // 不可达防御分支（上面 getEntity 已确认实体存在；computeState 内部同源查询不会翻案）
+        throw new HttpError(404, "ENTITY_NOT_FOUND", `实体不存在: ${target_id}`);
+    }
+    return c.json(ok(result));
+});
+//# sourceMappingURL=delta.js.map

package/dist/routes/delta.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"delta.js","sourceRoot":"","sources":["../../src/routes/delta.ts"],"names":[],"mappings":"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"}

package/dist/routes/entity.d.ts

@@ -0,0 +1,7 @@
+import { Hono } from "hono";
+import type { EntityType } from "@whispering233/ai-editor-shared";
+/** 实体路由（挂载于 /api/v1/entity，index.ts） */
+export declare const entityRoutes: Hono<import("hono/types").BlankEnv, import("hono/types").BlankSchema, "/">;
+/** 校验 :type 路径参数为合法实体类型（非法 → 400 VALIDATION_ERROR；trash 路由复用） */
+export declare function parseTypeParam(type: string): EntityType;
+//# sourceMappingURL=entity.d.ts.map

package/dist/routes/entity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity.d.ts","sourceRoot":"","sources":["../../src/routes/entity.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAE5B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAC;AAKlE,wCAAwC;AACxC,eAAO,MAAM,YAAY,4EAAa,CAAC;AAEvC,iEAAiE;AACjE,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAMvD"}

package/dist/routes/entity.js

@@ -0,0 +1,126 @@
+// 实体路由（S3.3）：GET 列表 / POST 创建 / GET 详情 / PUT 部分更新 / DELETE 软删
+//
+// 契约来源：doc/api/endpoints.md 第 124-276 行（实体 CRUD）、决策 12（软删级联）。
+// 错误映射（对照 endpoints.md 错误码）：
+//   type 参数非法 / 参数校验失败 → 400 VALIDATION_ERROR（zod 抛错由 errorHandler 统一映射，含 fields）
+//   实体不存在或已软删 → 404 ENTITY_NOT_FOUND
+import { Hono } from "hono";
+import { countDeltasForEntity, createEntity, getEntity, listEntities, listRelations, nowIso, softDeleteEntity, updateEntity } from "@whispering233/ai-editor-db";
+import { ENTITY_DATA_SCHEMAS, entityCreateReqSchema, entityListQuerySchema, entityTypeSchema, entityUpdateReqSchema } from "@whispering233/ai-editor-shared/schemas";
+import { HttpError, ok } from "../middleware/error.js";
+import { requireCurrentProject } from "../middleware/project.js";
+/** 实体路由（挂载于 /api/v1/entity，index.ts） */
+export const entityRoutes = new Hono();
+/** 校验 :type 路径参数为合法实体类型（非法 → 400 VALIDATION_ERROR；trash 路由复用） */
+export function parseTypeParam(type) {
+    const parsed = entityTypeSchema.safeParse(type);
+    if (!parsed.success) {
+        throw new HttpError(400, "VALIDATION_ERROR", `非法实体类型: ${type}`);
+    }
+    return parsed.data;
+}
+/** 按类型精确校验 data（endpoints.md 第 211-216 行：各 type 的 data 字段 schema；宽松 record 之外的精校验） */
+function validateDataByType(type, data) {
+    const check = ENTITY_DATA_SCHEMAS[type].safeParse(data);
+    if (!check.success) {
+        throw check.error; // → errorHandler → 400 VALIDATION_ERROR（含 fields）
+    }
+}
+// GET /api/v1/entity/:type —— 列表（q/offset/limit/sort/order；响应 camelCase）
+entityRoutes.get("/:type", (c) => {
+    const project = requireCurrentProject();
+    const type = parseTypeParam(c.req.param("type"));
+    const parsed = entityListQuerySchema.safeParse(c.req.query());
+    if (!parsed.success)
+        throw parsed.error;
+    const { q, offset, limit, sort, order } = parsed.data;
+    const result = listEntities(project.db, { type, q, offset, limit, sort, order });
+    return c.json(ok({
+        items: result.items, // EntitySummary（db 已提取：id/type/name/summary/createdAt/updatedAt，camelCase）
+        total: result.total,
+        offset: offset ?? 0,
+        limit: limit ?? 50,
+    }));
+});
+// GET /api/v1/entity/:type/:id —— 详情（含紧邻 relations + deltaCount）
+entityRoutes.get("/:type/:id", (c) => {
+    const project = requireCurrentProject();
+    parseTypeParam(c.req.param("type"));
+    const id = c.req.param("id");
+    const row = getEntity(project.db, id);
+    if (row === null) {
+        throw new HttpError(404, "ENTITY_NOT_FOUND", `实体不存在: ${id}`);
+    }
+    const deltaCount = countDeltasForEntity(project.db, id);
+    // relations 紧邻（S3.2：listRelations depth=1，任一端点软删即不可见，决策 12 修订；
+    // outline.json 校验路径 = project.root）。
+    // **双向邻接**（endpoints.md「紧邻 1 跳」未明示方向，产品语义为展示所有关联）：
+    // source 方向（该实体作为起点） + target 方向（该实体作为终点）两次查询，
+    // 按关系 id 去重（source 方向优先、保持稳定顺序；自环 A→A 两方向均命中但只出现一次）
+    const sourceRels = listRelations(project.db, { sourceId: row.id }, 1, project.root).relations;
+    const targetRels = listRelations(project.db, { targetId: row.id }, 1, project.root).relations;
+    const seenIds = new Set();
+    const relations = [...sourceRels, ...targetRels].filter((r) => {
+        if (seenIds.has(r.id))
+            return false;
+        seenIds.add(r.id);
+        return true;
+    });
+    return c.json(ok({
+        id: row.id,
+        type: row.type,
+        name: row.name,
+        data: row.data,
+        relations,
+        deltaCount,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+    }));
+});
+// POST /api/v1/entity/:type —— 创建（name 必填 1-100；data 按类型精确校验；201）
+entityRoutes.post("/:type", async (c) => {
+    const project = requireCurrentProject();
+    const type = parseTypeParam(c.req.param("type"));
+    const raw = await c.req.json().catch(() => null);
+    const parsed = entityCreateReqSchema.safeParse(raw);
+    if (!parsed.success)
+        throw parsed.error;
+    if (parsed.data.data !== undefined) {
+        validateDataByType(type, parsed.data.data);
+    }
+    const row = createEntity(project.db, { type, name: parsed.data.name, data: parsed.data.data });
+    return c.json(ok({ id: row.id, type: row.type, name: row.name, data: row.data, createdAt: row.created_at }), 201);
+});
+// PUT /api/v1/entity/:type/:id —— 部分更新（仅合并传入字段；data 浅合并）
+entityRoutes.put("/:type/:id", async (c) => {
+    const project = requireCurrentProject();
+    const type = parseTypeParam(c.req.param("type"));
+    const id = c.req.param("id");
+    const raw = await c.req.json().catch(() => null);
+    const parsed = entityUpdateReqSchema.safeParse(raw);
+    if (!parsed.success)
+        throw parsed.error;
+    if (parsed.data.data !== undefined) {
+        validateDataByType(type, parsed.data.data);
+    }
+    const row = updateEntity(project.db, id, parsed.data);
+    if (row === null) {
+        throw new HttpError(404, "ENTITY_NOT_FOUND", `实体不存在: ${id}`);
+    }
+    return c.json(ok({ id: row.id, updated: true }));
+});
+// DELETE /api/v1/entity/:type/:id —— 软删（决策 12：级联软删关系与 Delta，本体保留可还原）
+entityRoutes.delete("/:type/:id", (c) => {
+    const project = requireCurrentProject();
+    parseTypeParam(c.req.param("type"));
+    const id = c.req.param("id");
+    const result = softDeleteEntity(project.db, id, nowIso());
+    if (result === null) {
+        throw new HttpError(404, "ENTITY_NOT_FOUND", `实体不存在: ${id}`);
+    }
+    return c.json(ok({
+        deleted: true,
+        cascaded: { relations: result.relations, deltas: result.deltas },
+    }));
+});
+//# sourceMappingURL=entity.js.map

package/dist/routes/entity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity.js","sourceRoot":"","sources":["../../src/routes/entity.ts"],"names":[],"mappings":"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"}

package/dist/routes/outline.d.ts

@@ -0,0 +1,11 @@
+import { Hono } from "hono";
+import type { OutlineFileTree } from "@whispering233/ai-editor-shared";
+/** 大纲路由（挂载于 /api/v1/outline，index.ts） */
+export declare const outlineRoutes: Hono<import("hono/types").BlankEnv, import("hono/types").BlankSchema, "/">;
+/** 收集 nodeId 及其整棵子树的 id 集（含自身；供 relation/delta 级联软删/还原/清除用） */
+export declare function collectSubtreeIds(tree: OutlineFileTree, nodeId: string): string[];
+/** 生成 SQL IN 占位符串（id 集来自服务端生成的 nanoid，无注入面；空集返回 "(NULL)" 恒假） */
+export declare function inPlaceholders(ids: string[]): string;
+/** OutlineError → HttpError 映射（对照 endpoints.md 错误码，文件头注释表） */
+export declare function mapOutlineError(err: unknown): never;
+//# sourceMappingURL=outline.d.ts.map

package/dist/routes/outline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"outline.d.ts","sourceRoot":"","sources":["../../src/routes/outline.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAW5B,OAAO,KAAK,EAAmB,eAAe,EAA6C,MAAM,iCAAiC,CAAC;AAanI,yCAAyC;AACzC,eAAO,MAAM,aAAa,4EAAa,CAAC;AA4BxC,+DAA+D;AAC/D,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAajF;AAED,gEAAgE;AAChE,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,CAEpD;AA0LD,8DAA8D;AAC9D,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,KAAK,CAcnD"}

package/dist/routes/outline.js

@@ -0,0 +1,250 @@
+// 大纲路由（S2.2）：GET/POST /outline、PUT /outline/:nodeId、PUT move、DELETE、GET path
+//
+// 契约来源：doc/api/endpoints.md 第 516-657 行（大纲操作）、决策 12（软删/级联）、决策 19（严格三层）。
+// 错误映射（db OutlineError → HttpError，对照 endpoints.md 错误码）：
+//   NODE_NOT_FOUND             → 404 OUTLINE_NODE_NOT_FOUND
+//   PARENT_NOT_FOUND           → 400 OUTLINE_NODE_NOT_FOUND（父不存在是参数问题，非资源访问）
+//   INVALID_HIERARCHY          → 400 VALIDATION_ERROR（严格三层违反）
+//   OUTLINE_ANCESTOR_DELETED   → 409 OUTLINE_ANCESTOR_DELETED（决策 12 修订）
+// 说明：级联还原/物理清除（cascadeRestore/cascadePurge）已下沉 db 包 queries/trash.ts（S4.1）；
+//   级联软删（cascadeSoftDelete）保留在路由层——与软删端点同文件内联，S4.1 任务边界只下沉
+//   还原/清除两个 helper（trash.ts 路由直接 import @whispering233/ai-editor-db）。
+import { Hono } from "hono";
+import { findOutlineNode, readOutlineFile } from "@whispering233/ai-editor-db";
+import { getOutlinePathIds } from "@whispering233/ai-editor-db";
+import { createOutlineNode, deleteOutlineNode, moveOutlineNode, OutlineError, updateOutlineNodeInfo, } from "@whispering233/ai-editor-db";
+import { HOOK_RELATION_TYPES, mapOutlineFileToTree } from "@whispering233/ai-editor-shared";
+import { nowIso } from "@whispering233/ai-editor-db";
+import { outlineCreateReqSchema, outlineGetQuerySchema, outlineMoveReqSchema, outlineUpdateReqSchema, OUTLINE_NODE_DATA_SCHEMAS, } from "@whispering233/ai-editor-shared/schemas";
+import { HttpError, ok } from "../middleware/error.js";
+import { requireCurrentProject } from "../middleware/project.js";
+/** 大纲路由（挂载于 /api/v1/outline，index.ts） */
+export const outlineRoutes = new Hono();
+/**
+ * 按节点层级精确校验 data（决策 23：麦基字段集，OUTLINE_NODE_DATA_SCHEMAS；
+ * 宽松 record 之外的精校验，与 entity.ts validateDataByType 同构；
+ * 失败 → errorHandler → 400 VALIDATION_ERROR（含 fields））
+ */
+function validateNodeData(type, data) {
+    const check = OUTLINE_NODE_DATA_SCHEMAS[type].safeParse(data);
+    if (!check.success) {
+        throw check.error;
+    }
+}
+/** 递归过滤软删节点（决策 12：常规查询默认过滤；deleted 节点整棵子树丢弃） */
+function filterDeletedTree(tree) {
+    const filterNodes = (nodes) => nodes
+        .filter((n) => n.deleted !== true)
+        .map((n) => {
+        const kids = n.children;
+        return (kids === undefined ? { ...n } : { ...n, children: filterNodes(kids) });
+    });
+    // 递归产物为宽 OutlineFileNode[]，结构上满足严格三层（输入树合法 ⇒ 过滤后仍合法），
+    // 此处断言收窄回 OutlineFileTree（storage 形态判别联合的已知递归映射限制）
+    return { ...tree, children: filterNodes(tree.children) };
+}
+/** 收集 nodeId 及其整棵子树的 id 集（含自身；供 relation/delta 级联软删/还原/清除用） */
+export function collectSubtreeIds(tree, nodeId) {
+    const ids = [];
+    const visit = (nodes) => {
+        for (const n of nodes) {
+            if (n.id === nodeId || visit(n.children ?? [])) {
+                ids.push(n.id);
+                return true;
+            }
+        }
+        return false;
+    };
+    if (visit(tree.children))
+        return ids;
+    throw new HttpError(404, "OUTLINE_NODE_NOT_FOUND", `大纲节点不存在: ${nodeId}`);
+}
+/** 生成 SQL IN 占位符串（id 集来自服务端生成的 nanoid，无注入面；空集返回 "(NULL)" 恒假） */
+export function inPlaceholders(ids) {
+    return ids.length === 0 ? "(NULL)" : `(${ids.map(() => "?").join(",")})`;
+}
+/**
+ * 级联软删该节点及子树关联的 relation/delta（决策 12：任一端点软删即不可见）：
+ * - relations：source 或 target 命中子树任一节点 → 标 deleted_at（含 plot_edge 画布连线）
+ * - deltas：node_id 命中子树任一节点 → 标 deleted_at
+ * 返回 { relations, deltas } 实际级联数（UPDATE.changes）。
+ */
+function cascadeSoftDelete(db, subtreeIds, deletedAt) {
+    const rel = db
+        .prepare(`UPDATE relation_records SET deleted_at = ? WHERE deleted_at IS NULL AND
+       (source_id IN ${inPlaceholders(subtreeIds)} OR target_id IN ${inPlaceholders(subtreeIds)})`)
+        .run(deletedAt, ...subtreeIds, ...subtreeIds);
+    const delta = db
+        .prepare(`UPDATE delta_records SET deleted_at = ? WHERE deleted_at IS NULL AND node_id IN ${inPlaceholders(subtreeIds)}`)
+        .run(deletedAt, ...subtreeIds);
+    return { relations: rel.changes, deltas: delta.changes };
+}
+// GET /api/v1/outline —— 完整大纲树（软删过滤；with_metadata=true 联查统计）
+outlineRoutes.get("/", (c) => {
+    const project = requireCurrentProject();
+    const query = outlineGetQuerySchema.safeParse(c.req.query());
+    if (!query.success) {
+        throw query.error;
+    }
+    const tree = readOutlineFile(project.root);
+    // shared 映射（oracle 回修后支持决策 19「chapter 直挂 root」——换回 mapOutlineFileToTree，
+    // 删除 S2.2 的自写 mapTreeToApi 绕过）
+    const apiTree = mapOutlineFileToTree(filterDeletedTree(tree));
+    if (query.data.with_metadata === true) {
+        attachMetadata(apiTree, project.db);
+    }
+    return c.json(ok(apiTree));
+});
+/**
+ * with_metadata 联查统计（跨 outline.json × data.db，endpoints.md 第 523 行）：
+ * - hookCount：该节点出发的伏笔管理关系（plants/advances/resolves，source=outline_node → hook，hooks.md）
+ * - charCount：appears_in 指向该节点的关系数（决策 2 示例：char → 大纲节点）
+ * - deltaCount：该节点触发的 Delta 数（delta_records.node_id）
+ * 均为运行时计算，不写回数据（决策 21 _health 同款口径）。
+ */
+function attachMetadata(tree, db) {
+    const hookStmt = db.prepare(`SELECT COUNT(*) AS c FROM relation_records
+     WHERE source_type = 'outline_node' AND source_id = ?
+       AND relation_type IN (${HOOK_RELATION_TYPES.map(() => "?").join(",")})
+       AND deleted_at IS NULL`);
+    const charStmt = db.prepare(`SELECT COUNT(*) AS c FROM relation_records
+     WHERE target_type = 'outline_node' AND target_id = ? AND relation_type = 'appears_in'
+       AND deleted_at IS NULL`);
+    const deltaStmt = db.prepare(`SELECT COUNT(*) AS c FROM delta_records WHERE node_id = ? AND deleted_at IS NULL`);
+    const visit = (node) => {
+        const metadata = {};
+        metadata.hookCount = hookStmt.get(node.id, ...HOOK_RELATION_TYPES).c;
+        metadata.charCount = charStmt.get(node.id).c;
+        metadata.deltaCount = deltaStmt.get(node.id).c;
+        node.metadata = metadata;
+        for (const child of node.children ?? [])
+            visit(child);
+    };
+    for (const vol of tree.children)
+        visit(vol);
+}
+// POST /api/v1/outline —— 创建节点（严格三层，parent_id 必填，决策 19；data 按层级精校验，决策 23）
+outlineRoutes.post("/", async (c) => {
+    const project = requireCurrentProject();
+    const raw = await c.req.json().catch(() => null);
+    const parsed = outlineCreateReqSchema.safeParse(raw);
+    if (!parsed.success) {
+        throw parsed.error; // → 400 VALIDATION_ERROR（含 fields）
+    }
+    const { type, title, parent_id, summary, data } = parsed.data;
+    if (data !== undefined) {
+        validateNodeData(type, data);
+    }
+    let node;
+    try {
+        node = createOutlineNode(project.root, { type, title, parentId: parent_id, summary, data, updatedAt: nowIso() });
+    }
+    catch (err) {
+        throw mapOutlineError(err);
+    }
+    return c.json(ok({
+        id: node.id,
+        type: node.type,
+        title: node.title,
+        parentId: parent_id,
+        updatedAt: node.updated_at,
+    }), 201);
+});
+// PUT /api/v1/outline/:nodeId —— 更新标题/描述/结构化 data（data 部分合并，决策 23）
+outlineRoutes.put("/:nodeId", async (c) => {
+    const project = requireCurrentProject();
+    const raw = await c.req.json().catch(() => null);
+    const parsed = outlineUpdateReqSchema.safeParse(raw);
+    if (!parsed.success) {
+        throw parsed.error;
+    }
+    const nodeId = c.req.param("nodeId");
+    // data 精校验需要节点实际层级（请求体不含 type）：先定位节点（404 语义），再按层级校验
+    if (parsed.data.data !== undefined) {
+        const node = findOutlineNode(readOutlineFile(project.root), nodeId);
+        if (node === undefined) {
+            throw new HttpError(404, "OUTLINE_NODE_NOT_FOUND", `大纲节点不存在: ${nodeId}`);
+        }
+        validateNodeData(node.type, parsed.data.data);
+    }
+    try {
+        updateOutlineNodeInfo(project.root, nodeId, parsed.data, nowIso());
+    }
+    catch (err) {
+        throw mapOutlineError(err);
+    }
+    return c.json(ok({ updated: true }));
+});
+// PUT /api/v1/outline/:nodeId/move —— 移动/重排（严格三层约束同创建）
+outlineRoutes.put("/:nodeId/move", async (c) => {
+    const project = requireCurrentProject();
+    const raw = await c.req.json().catch(() => null);
+    const parsed = outlineMoveReqSchema.safeParse(raw);
+    if (!parsed.success) {
+        throw parsed.error;
+    }
+    let result;
+    try {
+        result = moveOutlineNode(project.root, c.req.param("nodeId"), { parentId: parsed.data.parent_id, order: parsed.data.order }, // snake_case → camelCase
+        nowIso());
+    }
+    catch (err) {
+        throw mapOutlineError(err);
+    }
+    return c.json(ok({ moved: true, ...result }));
+});
+// DELETE /api/v1/outline/:nodeId —— 软删 + 递归级联（决策 12）
+// 写序（决策 16）：**先 DB 后 JSON**——先级联软删 relation/delta，再原子写 outline.json；
+// 崩溃残留方向（DB 已级联、JSON 未标，节点未标 deleted）：无法从 DB 记录可靠反推
+// （实体侧级联会软删节点↔实体关系而节点仍存活），不在 S4.2 补标范围；
+// S4.2 启动一致性校验（consistency.ts）兜底幽灵反向：节点已软删而关联 relation/delta
+// 未软删 → 以节点软删为准补标 DB 记录（决策 16 修订，幂等自愈）
+outlineRoutes.delete("/:nodeId", (c) => {
+    const project = requireCurrentProject();
+    const nodeId = c.req.param("nodeId");
+    const tree = readOutlineFile(project.root);
+    const subtreeIds = collectSubtreeIds(tree, nodeId); // 404 语义
+    const deletedAt = nowIso();
+    // 1. DB 级联软删关联关系与 Delta（决策 12：节点/端点软删即不可见）
+    const { relations, deltas } = cascadeSoftDelete(project.db, subtreeIds, deletedAt);
+    // 2. JSON 原子写（软删节点 + 递归子树，决策 19 版本戳）
+    let children;
+    try {
+        children = deleteOutlineNode(project.root, nodeId, deletedAt).children;
+    }
+    catch (err) {
+        throw mapOutlineError(err);
+    }
+    return c.json(ok({ deleted: true, cascaded: { children, relations, deltas } }));
+});
+// GET /api/v1/outline/:nodeId/path —— 根 → 节点路径
+outlineRoutes.get("/:nodeId/path", (c) => {
+    const project = requireCurrentProject();
+    const nodeId = c.req.param("nodeId");
+    const tree = readOutlineFile(project.root);
+    let path;
+    try {
+        path = getOutlinePathIds(tree, nodeId);
+    }
+    catch {
+        throw new HttpError(404, "OUTLINE_NODE_NOT_FOUND", `大纲节点不存在: ${nodeId}`);
+    }
+    return c.json(ok({ nodeId, path }));
+});
+/** OutlineError → HttpError 映射（对照 endpoints.md 错误码，文件头注释表） */
+export function mapOutlineError(err) {
+    if (err instanceof OutlineError) {
+        switch (err.code) {
+            case "NODE_NOT_FOUND":
+                throw new HttpError(404, "OUTLINE_NODE_NOT_FOUND", err.message);
+            case "PARENT_NOT_FOUND":
+                throw new HttpError(400, "OUTLINE_NODE_NOT_FOUND", err.message);
+            case "INVALID_HIERARCHY":
+                throw new HttpError(400, "VALIDATION_ERROR", err.message);
+            case "OUTLINE_ANCESTOR_DELETED":
+                throw new HttpError(409, "OUTLINE_ANCESTOR_DELETED", err.message);
+        }
+    }
+    throw err instanceof Error ? err : new HttpError(500, "INTERNAL_ERROR", "大纲操作失败");
+}
+//# sourceMappingURL=outline.js.map

package/dist/routes/outline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"outline.js","sourceRoot":"","sources":["../../src/routes/outline.ts"],"names":[],"mappings":"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"}

package/dist/routes/project.d.ts

@@ -0,0 +1,27 @@
+import { Hono } from "hono";
+/** 设置创作根（index.ts startServer 调用；测试隔离用传 null 重置） */
+export declare function setProjectRoot(root: string | null): void;
+/** books/ 子目录名（书架模式：创作根/books/<书名>/） */
+export declare const BOOKS_DIR_NAME = "books";
+/**
+ * 规范化并校验项目路径（决策 17，create/open 通用）：
+ *
+ * 1. **必须是绝对路径**：endpoints.md 契约要求绝对路径；path.resolve 对相对输入会基于
+ *    process.cwd() 折叠，语义歧义（cwd 变化结果即变），显式拒绝
+ * 2. **path.resolve 规范化**：折叠 `..` 与重复分隔符（防 `..` 逃逸——规范化后即为最终操作目录，
+ *    不再拼接用户输入）
+ * 3. **realpath 一致性校验**：解析后的真实路径（符号链接展开）必须与规范化路径一致，否则拒绝——
+ *    校验语义（决策 17「防越权读写任意目录」）：本应用单项目根模型下「允许范围」即规范化后的
+ *    路径本身，符号链接会把读写导向意外位置（链接指向任意目录即越权），故链接跳转一律拒绝
+ *
+ * 调用方约定：create 流程在调用前先 mkdirSync（目录可能尚不存在，realpath 需要目录存在）；
+ * open 流程目录不存在时 realpath 抛错 → 同样 400。
+ *
+ * @param rawPath 用户提供的路径（绝对路径）
+ * @returns 规范化后的项目目录绝对路径
+ * @throws HttpError 400 INVALID_PROJECT_PATH
+ */
+export declare function resolveProjectDir(rawPath: string): string;
+/** 项目路由（挂载于 /api/v1/project，index.ts） */
+export declare const projectRoutes: Hono<import("hono/types").BlankEnv, import("hono/types").BlankSchema, "/">;
+//# sourceMappingURL=project.d.ts.map

package/dist/routes/project.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project.d.ts","sourceRoot":"","sources":["../../src/routes/project.ts"],"names":[],"mappings":"AAoBA,OAAO,EAAE,IAAI,EAAgB,MAAM,MAAM,CAAC;AAwC1C,oDAAoD;AACpD,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAExD;AAED,wCAAwC;AACxC,eAAO,MAAM,cAAc,UAAU,CAAC;AAEtC;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAkBzD;AAED,yCAAyC;AACzC,eAAO,MAAM,aAAa,4EAAa,CAAC"}