@siming-org/cli 0.3.0 → 0.4.0

package/dist/index.js

@@ -1,5 +1,5 @@
 // src/index.ts
-import { Command as Command15 } from "commander";
+import { Command as Command16 } from "commander";
 import { VERSION as VERSION5 } from "@siming-org/core";
 
 // src/output/fancy.ts
@@ -469,7 +469,7 @@ async function healthcheckCommand(opts) {
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
 // src/mcp/server.ts
-import { readFileSync as readFileSync6 } from "fs";
+import { readFileSync as readFileSync7 } from "fs";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { VERSION as VERSION3, EnumRegistryUpdateSchema } from "@siming-org/core";
 
@@ -495,6 +495,9 @@ async function handlePause(client, taskId, reason) {
 async function handleResume(client, taskId, decision) {
   return client.postJson(`/api/tasks/${taskId}/resume`, decision ? { decision } : {});
 }
+async function handleCancel(client, taskId, reason) {
+  return client.postJson(`/api/tasks/${taskId}/cancel`, reason !== void 0 ? { reason } : {});
+}
 async function handleListTasks(client, filters) {
   const qs = new URLSearchParams();
   if (filters?.status) qs.set("status", filters.status);
@@ -509,8 +512,8 @@ async function handleListTasks(client, filters) {
 async function handleQueryState(client, taskId) {
   return client.getJson(`/api/tasks/${taskId}`);
 }
-async function handleGetContext(client, taskId) {
-  return client.getJson(`/api/tasks/${taskId}/context`);
+async function handleGetContext(client, taskId, view) {
+  return client.getJson(`/api/tasks/${taskId}/context${view !== void 0 ? `?view=${view}` : ""}`);
 }
 async function handleGetNodePrompt(client, taskId, nodeId) {
   return client.getJson(`/api/tasks/${taskId}/node/${nodeId}`);
@@ -570,7 +573,11 @@ function handleArchNoteAdd(client, taskId, text) {
 // src/client/handlers/dag.ts
 import { readFileSync as readFileSync4 } from "fs";
 import { parse as parseYaml } from "yaml";
-import { DagTemplateCreateSchema } from "@siming-org/core";
+import {
+  DagTemplateCreateSchema,
+  ExportBundleSchema,
+  EXPORT_FORMAT_VERSION
+} from "@siming-org/core";
 async function handleListTemplates(client, projectId) {
   return client.getJson(`/api/dag/templates${projectId ? `?projectId=${encodeURIComponent(projectId)}` : ""}`);
 }
@@ -595,7 +602,11 @@ async function importTemplateFromYaml(client, yamlText, opts) {
   try {
     raw = parseYaml(yamlText);
   } catch (e) {
-    return fail({ message: `YAML \u89E3\u6790\u5931\u8D25: ${e instanceof Error ? e.message : String(e)}`, httpStatus: 0 });
+    return fail({
+      message: `YAML \u89E3\u6790\u5931\u8D25: ${e instanceof Error ? e.message : String(e)}`,
+      httpStatus: 0,
+      bizCode: "YAML_PARSE_FAILED"
+    });
   }
   const obj = raw ?? {};
   const projectId = opts.projectId ?? (typeof obj.projectId === "string" ? obj.projectId : void 0);
@@ -611,14 +622,56 @@ ${issues}`, httpStatus: 0 });
   }
   return client.postJson("/api/dag/templates", parsed.data);
 }
-async function handleImportTemplate(client, filePath, opts) {
-  let yamlText;
+async function importTemplateBundle(client, bundleText, opts) {
+  let raw;
   try {
-    yamlText = readFileSync4(filePath, "utf-8");
+    raw = JSON.parse(bundleText);
   } catch (e) {
-    return fail({ message: `\u6587\u4EF6\u8BFB\u53D6\u5931\u8D25: ${filePath}\uFF08${e instanceof Error ? e.message : String(e)}\uFF09`, httpStatus: 0 });
+    return fail({ message: `bundle \u89E3\u6790\u5931\u8D25: ${e instanceof Error ? e.message : String(e)}`, httpStatus: 0 });
+  }
+  const parsed = ExportBundleSchema.safeParse(raw);
+  if (!parsed.success) {
+    const issues = parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("\n");
+    const hasVersionField = typeof raw === "object" && raw !== null && "exportFormatVersion" in raw;
+    const versionMismatch = hasVersionField && parsed.error.issues.some((i) => i.path.includes("exportFormatVersion"));
+    return fail({
+      message: versionMismatch ? `bundle \u683C\u5F0F\u7248\u672C\u4E0D\u652F\u6301\uFF0C\u5F53\u524D\u652F\u6301 ${EXPORT_FORMAT_VERSION}\uFF0C\u8BF7\u5347\u7EA7 CLI \u7248\u672C
+${issues}` : `bundle \u6821\u9A8C\u5931\u8D25:
+${issues}`,
+      httpStatus: 0
+    });
   }
-  return importTemplateFromYaml(client, yamlText, opts);
+  const bundle = parsed.data;
+  const plan = await client.postJson("/api/dag/templates/import/plan", {
+    targetProjectId: opts.targetProjectId,
+    bundle
+  });
+  if (!plan.success) return plan;
+  if (opts.planOnly === true) return { success: true, data: { plan: plan.data } };
+  const decisions = [];
+  if (opts.overwriteDeps === true) {
+    for (const dep of plan.data.dependencies) {
+      if (dep.status !== "conflict") continue;
+      if (dep.kind === "modelAlias") {
+        decisions.push({ kind: "modelAlias", name: dep.name, action: "overwrite" });
+      } else if (dep.scope !== void 0) {
+        decisions.push({ kind: dep.kind, name: dep.name, scope: dep.scope, action: "overwrite" });
+      } else {
+        return fail({
+          message: `server plan \u54CD\u5E94\u5F02\u5E38\uFF1A${dep.kind} "${dep.name}" \u7F3A scope \u5B57\u6BB5`,
+          httpStatus: 0,
+          hint: "skill/agent \u4F9D\u8D56\u5FC5\u987B\u643A\u5E26 scope\u2014\u2014\u91CD\u8BD5\u4ECD\u590D\u73B0\u5219\u68C0\u67E5 server \u7248\u672C"
+        });
+      }
+    }
+  }
+  const apply = await client.postJson("/api/dag/templates/import/apply", {
+    targetProjectId: opts.targetProjectId,
+    bundle,
+    decisions
+  });
+  if (!apply.success) return apply;
+  return { success: true, data: { plan: plan.data, apply: apply.data } };
 }
 async function handleGetInstance(client, taskId) {
   const result = await client.getJson(`/api/tasks/${encodeURIComponent(taskId)}`);
@@ -640,6 +693,7 @@ async function handleListSkills(client, query) {
   const qs = new URLSearchParams();
   if (q.projectId) qs.set("projectId", q.projectId);
   if (q.scope) qs.set("scope", q.scope);
+  if (q.includeDisabled !== void 0) qs.set("includeDisabled", String(q.includeDisabled));
   const qstr = qs.toString();
   return client.getJson(`/api/skills${qstr ? `?${qstr}` : ""}`);
 }
@@ -669,6 +723,7 @@ async function handleListAgents(client, query) {
   const qs = new URLSearchParams();
   if (q.projectId) qs.set("projectId", q.projectId);
   if (q.scope) qs.set("scope", q.scope);
+  if (q.includeDisabled !== void 0) qs.set("includeDisabled", String(q.includeDisabled));
   const qstr = qs.toString();
   return client.getJson(`/api/agents${qstr ? `?${qstr}` : ""}`);
 }
@@ -861,12 +916,13 @@ import {
   ARTIFACT_TYPES,
   SkillScopeSchema,
   AgentScopeSchema,
+  AgentFunctionSchema,
   ProjectStatusSchema,
   EnumRegistryCategorySchema
 } from "@siming-org/core";
 var taskArgs = {
   action: z3.enum([
-    // 任务生命周期（8 机械映射 + query 例外：task list/show 合一）
+    // 任务生命周期（9 机械映射 + query 例外：task list/show 合一）
     "create",
     "query",
     "context",
@@ -875,6 +931,7 @@ var taskArgs = {
     "approve",
     "pause",
     "resume",
+    "cancel",
     "history",
     // 实例（例外：映射自 dag instance）
     "instance",
@@ -905,8 +962,9 @@ var taskArgs = {
   status: z3.string().optional(),
   page: z3.number().int().min(1).optional(),
   limit: z3.number().int().min(1).max(500).optional(),
-  // node
-  view: z3.enum(["prompt", "skills"]).optional(),
+  // node / context（T202608280007 D5：view 四值并集——node 只认 prompt|skills，
+  // context 只认 basic|full，per-action 校验归 mcp/server.ts；非法组合报失败三要素）
+  view: z3.enum(["prompt", "skills", "basic", "full"]).optional(),
   nodeId: z3.string().optional(),
   // advance / record-set（note 写 history；summary 写 nodeRecords，两位独立）
   note: z3.string().optional(),
@@ -949,6 +1007,10 @@ var syncArgs = {
   action: z3.enum(["run", "status"]),
   targetType: z3.enum(["skills", "agents", "all"]).optional()
 };
+var referenceDocSchema = z3.object({
+  path: z3.string(),
+  content: z3.string()
+});
 var skillArgs = {
   action: z3.enum(["list", "show", "create", "update", "copy", "delete"]),
   name: z3.string().optional(),
@@ -958,6 +1020,9 @@ var skillArgs = {
   content: z3.string().optional(),
   description: z3.string().optional(),
   version: z3.string().optional(),
+  /** create=初始引用集合；update=整笔替换（缺省 = 不修改；clearRefs=true = 清空） */
+  references: z3.array(referenceDocSchema).optional(),
+  clearRefs: z3.boolean().optional(),
   newName: z3.string().optional(),
   newScope: SkillScopeSchema.optional(),
   targetProjectId: z3.string().optional()
@@ -970,9 +1035,14 @@ var agentArgs = {
   description: z3.string().optional(),
   systemPrompt: z3.string().optional(),
   model: z3.string().optional(),
+  /** T202608260002：功能类型 reviewer|executor（缺省 executor）——仅 reviewer 在 install 落盘注入信息边界 */
+  "function": AgentFunctionSchema.optional(),
   tools: z3.array(z3.string()).optional(),
   permissions: z3.array(z3.string()).optional(),
   boundSkills: z3.array(z3.string()).optional(),
+  /** create=初始引用集合；update=整笔替换（缺省 = 不修改；clearRefs=true = 清空） */
+  references: z3.array(referenceDocSchema).optional(),
+  clearRefs: z3.boolean().optional(),
   newName: z3.string().optional(),
   newScope: AgentScopeSchema.optional(),
   targetProjectId: z3.string().optional()
@@ -1020,13 +1090,27 @@ var initArgs = {
 var doctorArgs = {};
 
 // src/client/handlers/export.ts
-function bumpPatch(version) {
-  const m = /^(\d+)\.(\d+)\.(\d+)$/.exec(version);
-  if (!m) return version;
-  return `${m[1]}.${m[2]}.${Number(m[3]) + 1}`;
+import { AGENT_MAIN_DOC, REFERENCE_LIMITS, SKILL_MAIN_DOC, bumpPatchOrPassthrough, createReferencesSchema, sumReferenceContentChars } from "@siming-org/core";
+function refsSuffix(base, references) {
+  return references !== void 0 ? `${base}\uFF0Crefs=${String(references.length)}` : base;
 }
 var isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
 var DEFAULT_VERSION = "1.0.0";
+function parseEntryReferences(entity, raw) {
+  if (!("references" in raw)) return {};
+  const rawRefs = raw.references;
+  if (!Array.isArray(rawRefs)) {
+    return { error: "references \u5FC5\u987B\u662F\u6570\u7EC4\uFF08\u952E\u7F3A\u5931 = \u4E0D\u4FEE\u6539\u670D\u52A1\u7AEF\u73B0\u503C\uFF1B\u663E\u5F0F [] = \u6E05\u7A7A\u5F15\u7528\u6587\u6863\uFF09" };
+  }
+  const parsed = createReferencesSchema(entity === "skill" ? SKILL_MAIN_DOC : AGENT_MAIN_DOC).safeParse(rawRefs);
+  if (!parsed.success) {
+    const first = parsed.error.issues[0];
+    return {
+      error: `references \u975E\u6CD5\uFF1A${first?.message ?? "\u6821\u9A8C\u5931\u8D25"}${parsed.error.issues.length > 1 ? `\uFF08\u5171 ${String(parsed.error.issues.length)} \u5904\u95EE\u9898\uFF09` : ""}`
+    };
+  }
+  return { refs: parsed.data };
+}
 function migrateLegacyPausePoints(edges, pausePoints) {
   if (pausePoints.length === 0) return edges;
   const result = edges.map((e) => isObject(e) ? { ...e } : e);
@@ -1077,6 +1161,16 @@ function normalizeExportEntries(raw) {
       errors.push({ name, type: "skill", action: "error", reason: "scope=project \u65F6\u5FC5\u586B projectKey", fieldPath: `skills[${i}].projectKey`, expected: "string (\u9879\u76EE key\uFF0C\u89C1 siming project list)" });
       continue;
     }
+    const skillRefs = parseEntryReferences("skill", item);
+    if (skillRefs.error !== void 0) {
+      errors.push({ name, type: "skill", action: "error", reason: skillRefs.error, fieldPath: `skills[${i}].references`, expected: `array of {path, content}\uFF08\u76F8\u5BF9\u8DEF\u5F84\uFF1B\u7981\u7EDD\u5BF9\u8DEF\u5F84/../\u53CD\u659C\u6760/\u4E3B\u6587\u6863\u540D ${SKILL_MAIN_DOC} \u51B2\u7A81\uFF09` });
+      continue;
+    }
+    const totalChars = item.content.length + sumReferenceContentChars(skillRefs.refs);
+    if (totalChars > REFERENCE_LIMITS.maxTotalChars) {
+      errors.push({ name, type: "skill", action: "error", reason: `\u4E3B\u6587\u6863\u4E0E\u5F15\u7528\u6587\u6863\u5185\u5BB9\u603B\u91CF ${String(totalChars)} \u5B57\u7B26\u8D85\u51FA\u805A\u5408\u4E0A\u9650 ${String(REFERENCE_LIMITS.maxTotalChars)}`, fieldPath: `skills[${i}].references`, expected: `\u603B\u91CF \u2264 ${String(REFERENCE_LIMITS.maxTotalChars)} \u5B57\u7B26` });
+      continue;
+    }
     skills.push({
       name,
       description: typeof item.description === "string" ? item.description : "",
@@ -1084,6 +1178,7 @@ function normalizeExportEntries(raw) {
       category: item.category === "domain" || item.category === "tooling" ? item.category : "process",
       version: typeof item.version === "string" && item.version ? item.version : DEFAULT_VERSION,
       scope,
+      ...skillRefs.refs !== void 0 ? { references: skillRefs.refs } : {},
       ...scope === "project" && typeof item.projectKey === "string" ? { projectKey: item.projectKey } : {},
       ...item.skipExisting === true ? { skipExisting: true } : {}
     });
@@ -1112,6 +1207,16 @@ function normalizeExportEntries(raw) {
       continue;
     }
     const strArr = (v) => Array.isArray(v) ? v.filter((x) => typeof x === "string") : [];
+    const agentRefs = parseEntryReferences("agent", item);
+    if (agentRefs.error !== void 0) {
+      errors.push({ name, type: "agent", action: "error", reason: agentRefs.error, fieldPath: `agents[${i}].references`, expected: `array of {path, content}\uFF08\u76F8\u5BF9\u8DEF\u5F84\uFF1B\u7981\u7EDD\u5BF9\u8DEF\u5F84/../\u53CD\u659C\u6760/\u4E3B\u6587\u6863\u540D ${AGENT_MAIN_DOC} \u51B2\u7A81\uFF09` });
+      continue;
+    }
+    const totalAgentChars = item.systemPrompt.length + sumReferenceContentChars(agentRefs.refs);
+    if (totalAgentChars > REFERENCE_LIMITS.maxTotalChars) {
+      errors.push({ name, type: "agent", action: "error", reason: `\u4E3B\u6587\u6863\u4E0E\u5F15\u7528\u6587\u6863\u5185\u5BB9\u603B\u91CF ${String(totalAgentChars)} \u5B57\u7B26\u8D85\u51FA\u805A\u5408\u4E0A\u9650 ${String(REFERENCE_LIMITS.maxTotalChars)}`, fieldPath: `agents[${i}].references`, expected: `\u603B\u91CF \u2264 ${String(REFERENCE_LIMITS.maxTotalChars)} \u5B57\u7B26` });
+      continue;
+    }
     agents.push({
       name,
       description: typeof item.description === "string" ? item.description : "",
@@ -1122,6 +1227,7 @@ function normalizeExportEntries(raw) {
       permissions: strArr(item.permissions),
       version: typeof item.version === "string" && item.version ? item.version : DEFAULT_VERSION,
       scope,
+      ...agentRefs.refs !== void 0 ? { references: agentRefs.refs } : {},
       ...scope === "project" && typeof item.projectKey === "string" ? { projectKey: item.projectKey } : {},
       ...item.skipExisting === true ? { skipExisting: true } : {}
     });
@@ -1203,7 +1309,7 @@ async function buildExportPlan(client, set, opts) {
         items.push({ name: s.name, type: "skill", action: "error", reason: `projectKey '${s.projectKey}' \u4E0D\u5B58\u5728`, hint: "check `siming project list` \u83B7\u53D6\u6B63\u786E\u7684 key", fieldPath: "projectKey" });
         continue;
       }
-      const existing = await client.getJson(`/api/skills/${encodeURIComponent(s.name)}`);
+      const existing = await client.getJson(`/api/skills/${encodeURIComponent(s.name)}?includeDisabled=true`);
       if (!existing.success && existing.error.httpStatus !== 404) {
         items.push({ name: s.name, type: "skill", action: "error", reason: `\u67E5\u8BE2 server \u5931\u8D25: ${existing.error.message}`, ...existing.error.hint ? { hint: existing.error.hint } : {}, fieldPath: "server" });
         continue;
@@ -1214,7 +1320,7 @@ async function buildExportPlan(client, set, opts) {
           name: s.name,
           type: "skill",
           action: "created",
-          reason: "server \u65E0\u540C\u540D\u8D44\u4EA7",
+          reason: refsSuffix("server \u65E0\u540C\u540D\u8D44\u4EA7", s.references),
           payload: {
             name: s.name,
             description: s.description,
@@ -1222,11 +1328,23 @@ async function buildExportPlan(client, set, opts) {
             category: s.category,
             version: s.version,
             scope: s.scope,
+            ...s.references !== void 0 ? { references: s.references } : {},
             ...s.scope === "project" ? { projectId } : {}
           }
         });
         continue;
       }
+      if (ex.enabled === false) {
+        items.push({
+          name: s.name,
+          type: "skill",
+          action: "error",
+          reason: "server \u5B58\u5728\u540C\u540D\u5DF2\u505C\u7528\u8D44\u4EA7\uFF08\u5217\u8868\u89C6\u56FE\u4E0D\u53EF\u89C1\uFF09",
+          hint: "\u5728 Web \u7BA1\u7406\u53F0\u91CD\u65B0\u542F\u7528\u8BE5\u8D44\u4EA7\u540E\u91CD\u8BD5 export\uFF0C\u6216\u4FEE\u6539\u672C\u5730\u6761\u76EE\u540D",
+          fieldPath: "server"
+        });
+        continue;
+      }
       if (ex.scope !== s.scope) {
         items.push({
           name: s.name,
@@ -1259,27 +1377,29 @@ async function buildExportPlan(client, set, opts) {
           name: s.name,
           type: "skill",
           action: "updated",
-          reason: `\u6761\u76EE\u7248\u672C ${s.version} \u2260 server ${serverVer ?? "\u65E0"}\uFF0C\u6309\u6761\u76EE\u7248\u672C\u66F4\u65B0`,
+          reason: refsSuffix(`\u6761\u76EE\u7248\u672C ${s.version} \u2260 server ${serverVer ?? "\u65E0"}\uFF0C\u6309\u6761\u76EE\u7248\u672C\u66F4\u65B0`, s.references),
           payload: {
             description: s.description,
             content: s.content,
             category: s.category,
             version: s.version,
+            ...s.references !== void 0 ? { references: s.references } : {},
             ...s.scope === "project" ? { projectId } : {}
           }
         });
       } else {
-        const next = bumpPatch(serverVer ?? s.version);
+        const next = bumpPatchOrPassthrough(serverVer ?? s.version);
         items.push({
           name: s.name,
           type: "skill",
           action: "updated",
-          reason: `\u7248\u672C\u76F8\u540C\uFF08${serverVer}\uFF09\uFF0C\u81EA\u52A8\u9012\u589E\u5230 ${next}`,
+          reason: refsSuffix(`\u7248\u672C\u76F8\u540C\uFF08${serverVer}\uFF09\uFF0C\u81EA\u52A8\u9012\u589E\u5230 ${next}`, s.references),
           payload: {
             description: s.description,
             content: s.content,
             category: s.category,
             version: next,
+            ...s.references !== void 0 ? { references: s.references } : {},
             ...s.scope === "project" ? { projectId } : {}
           }
         });
@@ -1305,7 +1425,7 @@ async function buildExportPlan(client, set, opts) {
         });
         continue;
       }
-      const existing = await client.getJson(`/api/agents/${encodeURIComponent(a.name)}`);
+      const existing = await client.getJson(`/api/agents/${encodeURIComponent(a.name)}?includeDisabled=true`);
       if (!existing.success && existing.error.httpStatus !== 404) {
         items.push({ name: a.name, type: "agent", action: "error", reason: `\u67E5\u8BE2 server \u5931\u8D25: ${existing.error.message}`, ...existing.error.hint ? { hint: existing.error.hint } : {}, fieldPath: "server" });
         continue;
@@ -1316,7 +1436,7 @@ async function buildExportPlan(client, set, opts) {
           name: a.name,
           type: "agent",
           action: "created",
-          reason: "server \u65E0\u540C\u540D\u8D44\u4EA7",
+          reason: refsSuffix("server \u65E0\u540C\u540D\u8D44\u4EA7", a.references),
           payload: {
             name: a.name,
             description: a.description,
@@ -1327,11 +1447,23 @@ async function buildExportPlan(client, set, opts) {
             permissions: a.permissions,
             version: a.version,
             scope: a.scope,
+            ...a.references !== void 0 ? { references: a.references } : {},
             ...a.scope === "project" ? { projectId } : {}
           }
         });
         continue;
       }
+      if (ex.enabled === false) {
+        items.push({
+          name: a.name,
+          type: "agent",
+          action: "error",
+          reason: "server \u5B58\u5728\u540C\u540D\u5DF2\u505C\u7528\u8D44\u4EA7\uFF08\u5217\u8868\u89C6\u56FE\u4E0D\u53EF\u89C1\uFF09",
+          hint: "\u5728 Web \u7BA1\u7406\u53F0\u91CD\u65B0\u542F\u7528\u8BE5\u8D44\u4EA7\u540E\u91CD\u8BD5 export\uFF0C\u6216\u4FEE\u6539\u672C\u5730\u6761\u76EE\u540D",
+          fieldPath: "server"
+        });
+        continue;
+      }
       if (ex.scope !== a.scope) {
         items.push({
           name: a.name,
@@ -1366,6 +1498,7 @@ async function buildExportPlan(client, set, opts) {
         boundSkills: a.boundSkills,
         tools: a.tools,
         permissions: a.permissions,
+        ...a.references !== void 0 ? { references: a.references } : {},
         ...a.scope === "project" ? { projectId } : {}
       };
       if (a.version !== serverVer) {
@@ -1373,16 +1506,16 @@ async function buildExportPlan(client, set, opts) {
           name: a.name,
           type: "agent",
           action: "updated",
-          reason: `\u6761\u76EE\u7248\u672C ${a.version} \u2260 server ${serverVer ?? "\u65E0"}\uFF0C\u6309\u6761\u76EE\u7248\u672C\u66F4\u65B0`,
+          reason: refsSuffix(`\u6761\u76EE\u7248\u672C ${a.version} \u2260 server ${serverVer ?? "\u65E0"}\uFF0C\u6309\u6761\u76EE\u7248\u672C\u66F4\u65B0`, a.references),
           payload: { ...patch, version: a.version }
         });
       } else {
-        const next = bumpPatch(serverVer ?? a.version);
+        const next = bumpPatchOrPassthrough(serverVer ?? a.version);
         items.push({
           name: a.name,
           type: "agent",
           action: "updated",
-          reason: `\u7248\u672C\u76F8\u540C\uFF08${serverVer}\uFF09\uFF0C\u81EA\u52A8\u9012\u589E\u5230 ${next}`,
+          reason: refsSuffix(`\u7248\u672C\u76F8\u540C\uFF08${serverVer}\uFF09\uFF0C\u81EA\u52A8\u9012\u589E\u5230 ${next}`, a.references),
           payload: { ...patch, version: next }
         });
       }
@@ -1396,7 +1529,8 @@ async function buildExportPlan(client, set, opts) {
         continue;
       }
       const listR = await client.getJson(
-        `/api/dag/templates?projectId=${encodeURIComponent(projectId)}&name=${encodeURIComponent(d.name)}`
+        // T202608290001：includeDisabled=true——停用模板与不存在区分（否则缺省过滤 → 误判 created → apply 撞 {projectId,name} 唯一索引 409）
+        `/api/dag/templates?projectId=${encodeURIComponent(projectId)}&name=${encodeURIComponent(d.name)}&includeDisabled=true`
       );
       if (!listR.success) {
         items.push({ name: d.name, type: "dag", action: "error", reason: `\u67E5\u8BE2 server \u5931\u8D25: ${listR.error.message}`, ...listR.error.hint ? { hint: listR.error.hint } : {}, fieldPath: "server" });
@@ -1416,6 +1550,17 @@ async function buildExportPlan(client, set, opts) {
         items.push({ name: d.name, type: "dag", action: "created", reason: `\u9879\u76EE ${d.projectKey} \u5185\u65E0\u540C\u540D\u6A21\u677F`, payload: createPayload });
         continue;
       }
+      if (ex.enabled === false) {
+        items.push({
+          name: d.name,
+          type: "dag",
+          action: "error",
+          reason: "server \u5B58\u5728\u540C\u540D\u5DF2\u505C\u7528\u6A21\u677F\uFF08\u5217\u8868\u89C6\u56FE\u4E0D\u53EF\u89C1\uFF09",
+          hint: "\u5728 Web \u7BA1\u7406\u53F0\u91CD\u65B0\u542F\u7528\u8BE5\u6A21\u677F\u540E\u91CD\u8BD5 export\uFF0C\u6216\u4FEE\u6539\u672C\u5730\u6761\u76EE\u540D",
+          fieldPath: "server"
+        });
+        continue;
+      }
       if (ex.projectId !== projectId) {
         items.push({ name: d.name, type: "dag", action: "error", reason: `\u5F52\u5C5E\u9879\u76EE\u4E0D\u4E00\u81F4\uFF1Aserver=${byId.get(ex.projectId) ?? ex.projectId} vs \u6761\u76EE=${d.projectKey}\uFF08\u5F52\u5C5E\u4E0D\u53EF\u53D8\uFF09`, hint: "\u8C03\u6574\u6761\u76EE projectKey \u6216\u5148\u5220\u9664\u518D\u5BFC\u5165", fieldPath: "projectKey" });
         continue;
@@ -1441,7 +1586,7 @@ async function buildExportPlan(client, set, opts) {
           targetId: ex.id
         });
       } else {
-        const next = bumpPatch(serverVer ?? d.version);
+        const next = bumpPatchOrPassthrough(serverVer ?? d.version);
         items.push({
           name: d.name,
           type: "dag",
@@ -1528,10 +1673,10 @@ async function applyExportPlan(client, plan, opts) {
 
 // src/commands/install/command.ts
 import { Command as Command2 } from "commander";
-import { existsSync as existsSync5, mkdirSync as mkdirSync4, writeFileSync as writeFileSync4 } from "fs";
+import { existsSync as existsSync5 } from "fs";
 import { createInterface } from "readline/promises";
 import { dirname as dirname3, join as join5 } from "path";
-import { VERSION as VERSION2 } from "@siming-org/core";
+import { AGENT_MAIN_DOC as AGENT_MAIN_DOC3, SKILL_MAIN_DOC as SKILL_MAIN_DOC3, VERSION as VERSION2 } from "@siming-org/core";
 
 // src/output/json.ts
 function renderJson(value) {
@@ -1639,8 +1784,10 @@ function renderResult(format, result, opts) {
 }
 
 // src/commands/opts.ts
+import { readFileSync as readFileSync5 } from "fs";
 import "commander";
 import { z as z4 } from "zod";
+import { canonicalizeReferencePath, createReferencesSchema as createReferencesSchema2 } from "@siming-org/core";
 function withCommonOpts(cmd, defaultFormat) {
   return cmd.option("--url <url>", "server base URL").option("--format <fmt>", "output format: fancy|table|json", defaultFormat);
 }
@@ -1659,13 +1806,63 @@ function parseEnum(value, schema, optName) {
   return ok2(r.data);
 }
 var SkillCategorySchema = z4.string().min(1);
+function parseRefFlags(refs, mainDocName) {
+  const docs = [];
+  const seen = /* @__PURE__ */ new Set();
+  const singlePathSchema = createReferencesSchema2(mainDocName);
+  for (const [index, spec] of refs.entries()) {
+    const at = spec.indexOf("@");
+    if (at <= 0 || at === spec.length - 1) {
+      return fail({
+        message: `--ref \u7B2C ${String(index + 1)} \u9879\u683C\u5F0F\u975E\u6CD5\uFF1A"${spec}"`,
+        httpStatus: 0,
+        hint: "\u683C\u5F0F\uFF1A<\u5F15\u7528\u76F8\u5BF9\u8DEF\u5F84>@<\u672C\u5730\u6587\u4EF6\u8DEF\u5F84>\uFF0C\u5982 references/guide.md@./docs/guide.md"
+      });
+    }
+    const relPath = spec.slice(0, at);
+    const localPath = spec.slice(at + 1);
+    const pathCheck = singlePathSchema.safeParse([{ path: relPath, content: "" }]);
+    if (!pathCheck.success) {
+      return fail({
+        message: `--ref \u76F8\u5BF9\u8DEF\u5F84\u975E\u6CD5\uFF1A${pathCheck.error.issues[0]?.message ?? relPath}`,
+        httpStatus: 0,
+        hint: "\u5F15\u7528\u8DEF\u5F84\u5FC5\u987B\u662F\u76F8\u5BF9\u8D44\u4EA7\u6839\u7684\u6B63\u659C\u6760\u76F8\u5BF9\u8DEF\u5F84\uFF08\u7981\u7EDD\u5BF9\u8DEF\u5F84 / .. \u56DE\u6EAF / \u53CD\u659C\u6760 / \u7A7A\u6BB5\uFF09"
+      });
+    }
+    if (seen.has(canonicalizeReferencePath(relPath))) {
+      return fail({
+        message: `--ref \u76F8\u5BF9\u8DEF\u5F84\u91CD\u590D\uFF1A"${relPath}"`,
+        httpStatus: 0,
+        hint: "\u540C\u4E00\u5F15\u7528\u8DEF\u5F84\u53EA\u80FD\u51FA\u73B0\u4E00\u6B21\uFF08\u5927\u5C0F\u5199/./ \u524D\u7F00\u5DEE\u5F02\u89C6\u4E3A\u76F8\u540C\u8DEF\u5F84\uFF09\uFF1B\u4E0D\u540C\u672C\u5730\u6587\u4EF6\u8BF7\u4F7F\u7528\u4E0D\u540C\u5F15\u7528\u8DEF\u5F84"
+      });
+    }
+    seen.add(canonicalizeReferencePath(relPath));
+    let content;
+    try {
+      content = readFileSync5(localPath, "utf-8");
+    } catch (e) {
+      return fail({
+        message: `--ref \u672C\u5730\u6587\u4EF6\u4E0D\u53EF\u8BFB\uFF1A"${localPath}"`,
+        httpStatus: 0,
+        hint: `\u786E\u8BA4\u6587\u4EF6\u5B58\u5728\u4E14\u53EF\u8BFB\uFF08${e instanceof Error ? e.message : String(e)}\uFF09`
+      });
+    }
+    docs.push({ path: relPath, content });
+  }
+  return ok2(docs);
+}
 
 // src/commands/install/writer.ts
-import { existsSync as existsSync4, mkdirSync as mkdirSync3, readFileSync as readFileSync5, renameSync as renameSync2, rmSync as rmSync2, writeFileSync as writeFileSync3 } from "fs";
+import { existsSync as existsSync4, mkdirSync as mkdirSync3, readFileSync as readFileSync6, renameSync as renameSync2, rmSync as rmSync2, writeFileSync as writeFileSync3 } from "fs";
 import { dirname as dirname2, join as join4 } from "path";
 import { homedir as homedir3 } from "os";
 import { parse as parseYaml2, stringify as stringifyYaml } from "yaml";
-import { VERSION } from "@siming-org/core";
+import {
+  AGENT_MAIN_DOC as AGENT_MAIN_DOC2,
+  SKILL_MAIN_DOC as SKILL_MAIN_DOC2,
+  VERSION,
+  createReferencesSchema as createReferencesSchema3
+} from "@siming-org/core";
 function agentsHomeDir() {
   const env = process.env.SIMING_AGENTS_HOME;
   return env && env.length > 0 ? env : join4(homedir3(), ".agents");
@@ -1688,6 +1885,24 @@ function isSafeAssetName(name) {
   if (name.includes("/") || name.includes("\\")) return false;
   return true;
 }
+var REFERENCE_SCHEMAS = {
+  [SKILL_MAIN_DOC2]: createReferencesSchema3(SKILL_MAIN_DOC2),
+  [AGENT_MAIN_DOC2]: createReferencesSchema3(AGENT_MAIN_DOC2)
+};
+function validateReferencesLocally(mainDocName, references) {
+  if (references === void 0) return null;
+  const parsed = REFERENCE_SCHEMAS[mainDocName].safeParse(references);
+  if (parsed.success) return null;
+  return parsed.error.issues[0]?.message ?? "references \u6821\u9A8C\u5931\u8D25";
+}
+function writeAssetDirectory(assetDir, files) {
+  rmSync2(assetDir, { recursive: true, force: true });
+  for (const file of files) {
+    const target = join4(assetDir, ...file.relPath.split("/"));
+    mkdirSync3(dirname2(target), { recursive: true });
+    writeFileSync3(target, file.content, "utf-8");
+  }
+}
 function skillToMarkdown(skill) {
   const fm = stringifyYaml(
     { name: skill.name, description: skill.description, "siming-version": skill.version },
@@ -1710,7 +1925,7 @@ function permissionsToMatrix(permissions) {
   }
   return matrix;
 }
-var AGENT_INFO_BOUNDARY = "\u4EFB\u52A1\u4F9D\u636E\u9650\u4E8E\u9879\u76EE\u4EE3\u7801\u3001\u5F00\u53D1\u6D41\u7A0B\u9636\u6BB5\u7684\u6267\u884C\u62A5\u544A/\u8BBE\u8BA1\u6587\u6863\u53CA\u59D4\u6D3E\u4EFB\u52A1\u63D0\u4F9B\u7684\u6750\u6599\uFF1B\u7981\u6B62\u81EA\u884C\u8BBF\u95EE\u65E5\u5FD7\u3001\u4E34\u65F6\u6587\u4EF6\u7B49\u8FC7\u7A0B\u4EA7\u7269\uFF0C\u59D4\u6D3E\u4EFB\u52A1\u660E\u786E\u8981\u6C42\u65F6\u9664\u5916\u3002";
+var AGENT_INFO_BOUNDARY = "\u4EFB\u52A1\u4F9D\u636E\u9650\u4E8E\u9879\u76EE\u4EE3\u7801\u3001\u8BBE\u8BA1\u6587\u6863/\u6267\u884C\u62A5\u544A\u53CA\u4EFB\u52A1\u4E0A\u4E0B\u6587\uFF08\u542B\u4EFB\u52A1\u4FE1\u606F\u3001\u63D0\u793A\u8BCD\u3001\u59D4\u6D3E\u6750\u6599\uFF09\uFF1B\u7981\u6B62\u81EA\u884C\u8BFB\u53D6\u65E5\u5FD7\u3001\u4E34\u65F6\u6587\u4EF6\u7B49\u8FC7\u7A0B\u4EA7\u7269\uFF0C\u7981\u6B62\u81EA\u884C\u6267\u884C\u6D4B\u8BD5\u3001\u547D\u4EE4\u6216\u5176\u4ED6\u64CD\u4F5C\uFF0C\u59D4\u6D3E\u4EFB\u52A1\u660E\u786E\u8981\u6C42\u65F6\u9664\u5916\u3002";
 function agentToMarkdown(agent, realModel) {
   const fm = {
     description: agent.description,
@@ -1724,7 +1939,8 @@ function agentToMarkdown(agent, realModel) {
   if (Object.keys(perms).length > 0) fm.permission = perms;
   const identity = "\u4F60\u662Fsubagent\uFF0C\u6B63\u5728\u63A5\u53D7\u4E3B\u4F1A\u8BDD\u7684\u59D4\u6D3E\u4EFB\u52A1\u3002";
   const skillLine = agent.boundSkills.length > 0 ? `\u8FD9\u4E2A\u4EFB\u52A1\u5FC5\u987B\u5148\u52A0\u8F7DSKILL\uFF1A${JSON.stringify(agent.boundSkills)} \u540E\u518D\u6267\u884C\u3002` : "";
-  const preamble = `${identity}${skillLine}${AGENT_INFO_BOUNDARY}`;
+  const boundary = agent["function"] === "reviewer" ? AGENT_INFO_BOUNDARY : "";
+  const preamble = `${identity}${skillLine}${boundary}`;
   return `---
 ${stringifyYaml(fm, { lineWidth: 0 })}---
 
@@ -1740,7 +1956,7 @@ function readSimingVersion(path) {
   if (!existsSync4(path)) return null;
   let text;
   try {
-    text = readFileSync5(path, "utf-8");
+    text = readFileSync6(path, "utf-8");
   } catch {
     return null;
   }
@@ -1765,7 +1981,7 @@ function readMcpConfig(path) {
   if (!existsSync4(path)) return { state: "absent" };
   let text;
   try {
-    text = readFileSync5(path, "utf-8");
+    text = readFileSync6(path, "utf-8");
   } catch (e) {
     return { state: "corrupt", error: `\u8BFB\u53D6\u5931\u8D25: ${e instanceof Error ? e.message : String(e)}` };
   }
@@ -1877,7 +2093,7 @@ function createInstallCommand() {
         (i) => (opts.only ?? []).length === 0 || (opts.only ?? []).includes(i.name)
       );
       const actionable = selectedItems.filter(
-        (i) => opts.force || i.action === "install" || i.action === "update"
+        (i) => !i.disabled && (opts.force || i.action === "install" || i.action === "update")
       );
       if (actionable.length === 0) {
         const t = resolveInstallTargets(scope);
@@ -1969,7 +2185,7 @@ function readWorkspaceConfigSafe(ws) {
   }
 }
 async function buildInstallPlan(client, scope, projectId, only) {
-  const listQuery = scope === "global" ? { scope: "global" } : { scope: "project", ...projectId ? { projectId } : {} };
+  const listQuery = scope === "global" ? { scope: "global", includeDisabled: true } : { scope: "project", ...projectId ? { projectId } : {}, includeDisabled: true };
   const skillsR = await handleListSkills(client, listQuery);
   const agentsR = await handleListAgents(client, listQuery);
   if (!skillsR.success) return skillsR;
@@ -2005,6 +2221,7 @@ async function buildInstallPlan(client, scope, projectId, only) {
 function compareSkill(s, dir) {
   const path = skillTargetPath(dir, s);
   const base = { name: s.name, type: "skill", serverVersion: s.version, action: "install", reason: "" };
+  if (s.enabled === false) return { ...base, action: "skip", reason: "server asset disabled", disabled: true };
   if (!isSafeAssetName(s.name)) {
     return { ...base, action: "conflict", reason: `unsafe asset name "${s.name}"` };
   }
@@ -2022,6 +2239,7 @@ function compareSkill(s, dir) {
 function compareAgent(a, dir) {
   const path = agentTargetPath(dir, a);
   const base = { name: a.name, type: "agent", serverVersion: a.version, action: "install", reason: "" };
+  if (a.enabled === false) return { ...base, action: "skip", reason: "server asset disabled", disabled: true };
   if (!isSafeAssetName(a.name)) {
     return { ...base, action: "conflict", reason: `unsafe asset name "${a.name}"` };
   }
@@ -2079,7 +2297,7 @@ async function applyInstall(client, scope, projectId, items, opts) {
   const results = [];
   const force = opts?.force ?? false;
   const actionable = items.filter(
-    (i) => force || i.action === "install" || i.action === "update"
+    (i) => !i.disabled && (force || i.action === "install" || i.action === "update")
   );
   const assetQuery = scope === "global" ? { scope: "global" } : { scope: "project", ...projectId ? { projectId } : {} };
   for (const item of actionable) {
@@ -2113,9 +2331,22 @@ async function applyInstall(client, scope, projectId, items, opts) {
           continue;
         }
         const targetPath = skillTargetPath(targets.dir, r.data);
+        const invalidRef = validateReferencesLocally(SKILL_MAIN_DOC3, r.data.references);
+        if (invalidRef !== null) {
+          results.push({ name: item.name, type: "skill", action: "failed", reason: `invalid reference doc from server: ${invalidRef}`, hint: "\u5F15\u7528\u6587\u6863\u975E\u6CD5\uFF08\u6570\u636E\u53EF\u80FD\u88AB\u7ED5\u8FC7\u6821\u9A8C\u5199\u5165\uFF09\uFF1B\u4FEE\u6B63 server \u6570\u636E\u540E\u91CD\u8BD5\uFF0C\u672C\u6761\u672A\u5199\u5165" });
+          continue;
+        }
         const targetExists = existsSync5(targetPath);
-        writeFile(targetPath, skillToMarkdown(r.data));
-        results.push({ name: item.name, type: "skill", action: targetExists ? "updated" : "installed" });
+        writeAssetDirectory(dirname3(targetPath), [
+          { relPath: SKILL_MAIN_DOC3, content: skillToMarkdown(r.data) },
+          ...(r.data.references ?? []).map((ref) => ({ relPath: ref.path, content: ref.content }))
+        ]);
+        results.push({
+          name: item.name,
+          type: "skill",
+          action: targetExists ? "updated" : "installed",
+          ...r.data.references?.length ? { reason: `${String(r.data.references.length)} reference doc(s) synced` } : {}
+        });
       } else {
         if (!isSafeAssetName(item.name)) {
           results.push({ name: item.name, type: "agent", action: "failed", reason: `unsafe asset name "${item.name}"`, hint: 'asset name must not contain path separators or "." / ".." segments' });
@@ -2136,9 +2367,22 @@ async function applyInstall(client, scope, projectId, items, opts) {
           continue;
         }
         const targetPath = agentTargetPath(targets.dir, r.data);
+        const invalidRef = validateReferencesLocally(AGENT_MAIN_DOC3, r.data.references);
+        if (invalidRef !== null) {
+          results.push({ name: item.name, type: "agent", action: "failed", reason: `invalid reference doc from server: ${invalidRef}`, hint: "\u5F15\u7528\u6587\u6863\u975E\u6CD5\uFF08\u6570\u636E\u53EF\u80FD\u88AB\u7ED5\u8FC7\u6821\u9A8C\u5199\u5165\uFF09\uFF1B\u4FEE\u6B63 server \u6570\u636E\u540E\u91CD\u8BD5\uFF0C\u672C\u6761\u672A\u5199\u5165" });
+          continue;
+        }
         const targetExists = existsSync5(targetPath);
-        writeFile(targetPath, agentToMarkdown(r.data, realModel));
-        results.push({ name: item.name, type: "agent", action: targetExists ? "updated" : "installed" });
+        writeAssetDirectory(dirname3(targetPath), [
+          { relPath: AGENT_MAIN_DOC3, content: agentToMarkdown(r.data, realModel) },
+          ...(r.data.references ?? []).map((ref) => ({ relPath: ref.path, content: ref.content }))
+        ]);
+        results.push({
+          name: item.name,
+          type: "agent",
+          action: targetExists ? "updated" : "installed",
+          ...r.data.references?.length ? { reason: `${String(r.data.references.length)} reference doc(s) synced` } : {}
+        });
       }
     } catch (e) {
       results.push({ name: item.name, type: item.type, action: "failed", reason: e instanceof Error ? e.message : String(e), hint: "\u68C0\u67E5\u76EE\u6807\u76EE\u5F55\u6743\u9650\u540E\u91CD\u8BD5\uFF1B\u5DF2\u5199\u5165\u6761\u76EE\u4E0D\u53D7\u5F71\u54CD\uFF08\u5E42\u7B49\uFF0C\u4FEE\u590D\u540E\u91CD\u8DD1\u81EA\u6108\uFF09" });
@@ -2152,12 +2396,12 @@ function buildInstallGuidance(scope, targets) {
   const lines = [];
   lines.push("\u2500\u2500 siming \u901A\u7528\u8D44\u4EA7\u8FC1\u79FB\u6307\u5F15\uFF08.agents \u5F00\u653E\u534F\u8BAE\u843D\u70B9\uFF09\u2500\u2500");
   lines.push(`[1] \u8D44\u4EA7\u4F4D\u7F6E\uFF08${scope === "global" ? "\u7528\u6237\u7EA7" : "\u9879\u76EE\u7EA7"} ${targets.dir}\uFF09\uFF1A`);
-  lines.push(`    - skills: ${join5(targets.dir, "skills")}\uFF08\u6BCF\u4E2A skill \u4E00\u4E2A\u5B50\u76EE\u5F55\uFF0C\u542B SKILL.md\uFF09`);
-  lines.push(`    - agents: ${join5(targets.dir, "agents")}\uFF08\u6BCF\u4E2A agent \u4E00\u4E2A\u5B50\u76EE\u5F55\uFF0C\u542B agent.md\uFF09`);
+  lines.push(`    - skills: ${join5(targets.dir, "skills")}\uFF08\u6BCF\u4E2A skill \u4E00\u4E2A\u5B50\u76EE\u5F55\uFF0C\u542B SKILL.md \u4E0E\u5176\u5F15\u7528\u6587\u6863\uFF09`);
+  lines.push(`    - agents: ${join5(targets.dir, "agents")}\uFF08\u6BCF\u4E2A agent \u4E00\u4E2A\u5B50\u76EE\u5F55\uFF0C\u542B agent.md \u4E0E\u5176\u5F15\u7528\u6587\u6863\uFF09`);
   if (targets.mcpConfigPath) {
     lines.push(`    - MCP \u6CE8\u518C: ${targets.mcpConfigPath}\uFF08\u9876\u5C42 mcpServers.siming \u2192 stdio \u547D\u4EE4 "siming mcp-serve"\uFF09`);
   }
-  lines.push("[2] \u5F15\u7528\u65B9\u5F0F\uFF1Askill = \u5B50\u76EE\u5F55\u5185 SKILL.md\uFF08frontmatter name/description\uFF09\uFF1Bagent = \u5B50\u76EE\u5F55\u5185 agent.md\uFF08frontmatter description/model/skills\uFF0C\u6B63\u6587\u542B\u7ED1\u5B9A Skill \u52A0\u8F7D\u6307\u4EE4\uFF09\u3002");
+  lines.push("[2] \u5F15\u7528\u65B9\u5F0F\uFF1Askill = \u5B50\u76EE\u5F55\u5185 SKILL.md\uFF08frontmatter name/description\uFF09\uFF1Bagent = \u5B50\u76EE\u5F55\u5185 agent.md\uFF08frontmatter description/model/skills\uFF0C\u6B63\u6587\u542B\u7ED1\u5B9A Skill \u52A0\u8F7D\u6307\u4EE4\uFF09\uFF1B\u5E26\u5F15\u7528\u6587\u6863\u7684\u8D44\u4EA7\uFF0C\u4E3B\u6587\u6863\u4E2D\u7684\u76F8\u5BF9\u8DEF\u5F84\u5F15\u7528\u5728\u5B50\u76EE\u5F55\u5185\u76F4\u63A5\u53EF\u8FBE\u3002");
   const mcpPart = targets.mcpConfigPath ? "\uFF1B\u628A mcpServers.siming \u6761\u76EE\u5408\u5E76\u8FDB\u672C\u5DE5\u5177\u7684 MCP \u914D\u7F6E" : "\uFF08\u9879\u76EE\u7EA7\u5B89\u88C5\u4E0D\u542B MCP \u6CE8\u518C\uFF0C\u9700\u8981\u65F6\u53E6\u884C\u6267\u884C\u7528\u6237\u7EA7 install\uFF09";
   lines.push(`[3] \u6CE8\u518C\u9014\u5F84\uFF08\u5F53\u524D\u7F16\u7A0B\u5DE5\u5177\u4F1A\u8BDD\u4E2D\u7684 AI \u53EF\u76F4\u63A5\u6267\u884C\uFF09\uFF1A\u628A skills \u5B50\u76EE\u5F55\u52A0\u5165\u672C\u5DE5\u5177\u7684 skill \u641C\u7D22\u8DEF\u5F84\uFF1B\u628A agent \u5B50\u76EE\u5F55\u6CE8\u518C\u8FDB\u672C\u5DE5\u5177\u7684 subagent \u914D\u7F6E${mcpPart}\u3002`);
   if (targets.mcpConfigPath) {
@@ -2174,10 +2418,6 @@ async function resolveAgentModel(client, agent) {
   const alias = r.data.find((a) => a.code === agent.model);
   return alias?.realModel ?? null;
 }
-function writeFile(path, content) {
-  mkdirSync4(dirname3(path), { recursive: true });
-  writeFileSync4(path, content, "utf-8");
-}
 function renderInstallPlan(format, plan, scope, targets) {
   if (format === "json") {
     renderResult("json", { success: true, data: { scope, ...targets ? { dir: targets.dir, mcpConfigPath: targets.mcpConfigPath } : {}, items: plan.items } });
@@ -2431,7 +2671,7 @@ function createDoctorCommand() {
 // src/mcp/server.ts
 function mcpContent(result) {
   const payload = result.success ? result.data : result.error;
-  const text = payload === void 0 ? "null" : JSON.stringify(payload, null, 2);
+  const text = payload === void 0 ? "null" : JSON.stringify(payload);
   return result.success ? { content: [{ type: "text", text }] } : { content: [{ type: "text", text }], isError: true };
 }
 function requireError(action, fields, args) {
@@ -2457,7 +2697,7 @@ function createMcpServer() {
   const currentProcessUrl = resolveServerUrl();
   server.tool(
     "siming_task",
-    "task \u8D44\u6E90\u57DF\u805A\u5408\u5DE5\u5177\uFF08\u4EFB\u52A1\u5168\u64CD\u4F5C\u7ECF\u672C\u5DE5\u5177 + action \u53C2\u6570\uFF09\u3002action \u5FC5\u586B\uFF0C\u5176\u4F59\u53C2\u6570\u5168\u53EF\u9009\u3001\u6309 action \u8FD0\u884C\u65F6\u6821\u9A8C\u5FC5\u586B\uFF08\u7F3A\u5931\u8FD4\u56DE\u5931\u8D25\u4E09\u8981\u7D20\uFF1A\u5BF9\u8C61+\u6839\u56E0+\u4FEE\u590D\u6307\u5F15\uFF09\u3002action \u6E05\u5355\uFF08\u62EC\u53F7\u5185\u4E3A\u8BE5 action \u5FC5\u586B\u53C2\u6570\uFF09\uFF1Acreate(templateId,taskTitle,track\uFF1B\u53EF\u9009 type=feature|bugfix|ui-tweak|research\u3001skipNodes\u3001projectId)\uFF1Bquery(taskId \u8FD4\u56DE\u5355\u4EFB\u52A1\u8BE6\u60C5\uFF0C\u7F3A\u7701\u8FD4\u56DE\u5217\u8868\uFF0C\u53EF\u9009 status/track/projectId/page/limit)\uFF1Bcontext(taskId\u2014\u2014\u63A8\u8FDB\u4EFB\u52A1\u524D\u4F18\u5148\u8C03\u7528)\uFF1Bnode(taskId,view=prompt|skills\uFF1BnodeId \u7F3A\u7701\u7528\u5F53\u524D\u8282\u70B9)\uFF1Badvance(taskId\uFF1Bnote \u5199 history\u3001summary \u5199 nodeRecords\uFF0C\u4E24\u4F4D\u72EC\u7ACB)\uFF1Bapprove(taskId,decision=approved|rejected\uFF1B\u53EF\u9009 comment)\uFF1Bpause(taskId\uFF1B\u53EF\u9009 reason)\uFF1Bresume(taskId\uFF1B\u53EF\u9009 resumeNote)\uFF1Bhistory(taskId)\uFF1Binstance(taskId\u2014\u2014\u67E5\u770B\u4EFB\u52A1 DAG \u5B9E\u4F8B\u5FEB\u7167\uFF1A\u521B\u5EFA\u4EFB\u52A1\u65F6\u51BB\u7ED3\u7684\u6A21\u677F\u5B9E\u4F8B\uFF0C\u6A21\u677F\u540E\u7EED\u53D8\u66F4\u4E0D\u56DE\u6EAF)\u3002\u8BB0\u5F55\u5199\u5165\uFF1Arecord-set(taskId,node,summary)\uFF1Brecord-check-add(taskId,node,item\uFF1B\u53EF\u9009 passed \u7F3A\u7701 true)\uFF1Brecord-check-patch(taskId,node,checkId\uFF1B\u53EF\u9009 passed)\uFF1Brecord-artifact-add(taskId,node,artifactType=prd|tech|code|test|doc|other\uFF1Bpath \u7EAF\u5F15\u7528 / file \u8BFB\u672C\u673A\u6587\u4EF6 / content \u76F4\u4F20\u5168\u6587\u2014\u2014file \u4E0E content\u3001file \u4E0E path \u4E92\u65A5\uFF0Ccontent \u53EF\u4E0E path \u6210\u5BF9\u6216\u5355\u72EC\uFF0C\u5355\u72EC\u65F6\u767B\u8BB0\u503C\u5408\u6210 mcp-inline/<type>\uFF1B\u53EF\u9009 note)\uFF1Brecord-confirm(taskId,node,quote\u2014\u2014\u6682\u505C\u70B9\u7528\u6237\u786E\u8BA4\u539F\u6587\u9010\u5B57)\uFF1Brecord-decision-add(taskId,node,topic,decisionText)\uFF1Brecord-review-set(taskId,node,verdict=pass|fail,rounds,critical)\u3002\u9700\u6C42\u6587\u6863\uFF1Adoc-set(taskId\uFF1Bwhat/why/trackNote \u81F3\u5C11\u4F20\u4E00)\uFF1Bdoc-acceptance-add(taskId,text)\uFF1Bdoc-non-goal-add(taskId,text)\u3002\u7D20\u6750\uFF1Aarchnote-add(taskId,text)\u3002",
+    "task \u8D44\u6E90\u57DF\u805A\u5408\u5DE5\u5177\uFF08\u4EFB\u52A1\u5168\u64CD\u4F5C\u7ECF\u672C\u5DE5\u5177 + action \u53C2\u6570\uFF09\u3002action \u5FC5\u586B\uFF0C\u5176\u4F59\u53C2\u6570\u5168\u53EF\u9009\u3001\u6309 action \u8FD0\u884C\u65F6\u6821\u9A8C\u5FC5\u586B\uFF08\u7F3A\u5931\u8FD4\u56DE\u5931\u8D25\u4E09\u8981\u7D20\uFF1A\u5BF9\u8C61+\u6839\u56E0+\u4FEE\u590D\u6307\u5F15\uFF09\u3002\u5199\u64CD\u4F5C\uFF08create/doc-*/record-*/archnote-add/pause/resume/cancel\uFF09\u54CD\u5E94\u4E3A\u8F7B\u91CF\u56DE\u6267\uFF1A{taskId, updated(\u89E6\u53CA\u5B57\u6BB5\u8DEF\u5F84), entry(\u65B0\u6761\u76EE id+kind\uFF0C\u4F9B\u540E\u7EED patch \u5B9A\u4F4D), echo(\u5199\u5165\u5185\u5BB9\u56DE\u663E), updatedAt, task(\u4EFB\u52A1\u8FDB\u5EA6\u6458\u8981 progress: {completed,total})}\u2014\u2014\u4E0D\u8FD4\u56DE\u5B8C\u6574\u4EFB\u52A1\u5B9E\u4F53\u3002action \u6E05\u5355\uFF08\u62EC\u53F7\u5185\u4E3A\u8BE5 action \u5FC5\u586B\u53C2\u6570\uFF09\uFF1Acreate(templateId,taskTitle,track\uFF1B\u53EF\u9009 type=feature|bugfix|ui-tweak|research\u3001skipNodes\u3001projectId\uFF1B\u54CD\u5E94 {task, firstNode}\u2014\u2014firstNode \u5373\u9996\u8282\u70B9\u5B8C\u6574\u8D44\u6599\u5305\uFF0C\u514D\u8C03 context)\uFF1Bquery(taskId \u8FD4\u56DE\u5355\u4EFB\u52A1\u8BE6\u60C5\uFF0C\u7F3A\u7701\u8FD4\u56DE\u5217\u8868\uFF0C\u53EF\u9009 status/track/projectId/page/limit)\uFF1Bcontext(taskId\uFF1B\u53EF\u9009 view=basic|full\u2014\u2014basic \u7F3A\u7701\u4E0D\u643A\u5E26 artifact \u5168\u6587\u5FEB\u7167\uFF0Cfull \u65AD\u70B9\u7EED\u8DD1\u9700\u5386\u53F2\u4EA7\u7269\u5168\u6587\u65F6\u7528\u3002\u26A0 \u514D\u91CD\u8BFB\uFF1Aadvance/approve \u6D41\u8F6C\u54CD\u5E94\u5DF2\u542B\u4E0B\u4E00\u8282\u70B9\u5B8C\u6574\u8D44\u6599\u5305\uFF0C\u540C\u4F1A\u8BDD\u5185\u6D41\u8F6C\u540E\u76F4\u63A5\u5F00\u5DE5\u3001\u65E0\u9700\u518D\u8C03 context\uFF1B\u4EC5\u65B0\u4F1A\u8BDD/\u65AD\u70B9\u7EED\u8DD1\u8C03\u7528)\uFF1Bnode(taskId,view=prompt|skills\uFF1BnodeId \u7F3A\u7701\u7528\u5F53\u524D\u8282\u70B9\uFF1B\u26A0 view \u503C\u968F action \u4E0D\u540C\uFF1Anode\u2192prompt|skills\uFF0Ccontext\u2192basic|full\uFF0C\u9519\u914D\u62A5\u9519)\uFF1Badvance(taskId\uFF1Bnote \u5199 history\u3001summary \u5199 nodeRecords\uFF0C\u4E24\u4F4D\u72EC\u7ACB\uFF1B\u54CD\u5E94\u5DF2\u542B\u4E0B\u4E00\u8282\u70B9\u8D44\u6599\u5305\uFF0C\u540C\u4F1A\u8BDD\u514D\u91CD\u8BFB context)\uFF1Bapprove(taskId,decision=approved|rejected\uFF1B\u53EF\u9009 comment\uFF1B\u54CD\u5E94\u5DF2\u542B\u4E0B\u4E00\u8282\u70B9\u8D44\u6599\u5305\uFF0C\u540C\u4F1A\u8BDD\u514D\u91CD\u8BFB context)\uFF1Bpause(taskId\uFF1B\u53EF\u9009 reason)\uFF1Bresume(taskId\uFF1B\u53EF\u9009 resumeNote)\uFF1Bcancel(taskId\uFF1B\u53EF\u9009 reason 1-500 \u5B57\u7B26\uFF1B\u26A0 \u7EC8\u6001\u4E0D\u53EF\u9006\u2014\u2014active/paused \u53EF\u53D6\u6D88\uFF0Ccompleted/cancelled \u62D2\u7EDD\u5E76\u8FD4\u56DE TASK_TERMINATED\uFF1B\u53D6\u6D88\u540E\u7ECF\u672C\u5DE5\u5177\u7684\u6D41\u8F6C\u4E0E\u8BB0\u5F55\u5199\u64CD\u4F5C\u88AB\u62D2)\uFF1Bhistory(taskId)\uFF1Binstance(taskId\u2014\u2014\u67E5\u770B\u4EFB\u52A1 DAG \u5B9E\u4F8B\u5FEB\u7167\uFF1A\u521B\u5EFA\u4EFB\u52A1\u65F6\u51BB\u7ED3\u7684\u6A21\u677F\u5B9E\u4F8B\uFF0C\u6A21\u677F\u540E\u7EED\u53D8\u66F4\u4E0D\u56DE\u6EAF)\u3002\u8BB0\u5F55\u5199\u5165\uFF1Arecord-set(taskId,node,summary)\uFF1Brecord-check-add(taskId,node,item\uFF1B\u53EF\u9009 passed \u7F3A\u7701 true\uFF1B\u56DE\u6267 entry.id \u4F9B record-check-patch \u5B9A\u4F4D)\uFF1Brecord-check-patch(taskId,node,checkId\uFF1B\u53EF\u9009 passed)\uFF1Brecord-artifact-add(taskId,node,artifactType=prd|tech|code|test|doc|other\uFF1Bpath \u7EAF\u5F15\u7528 / file \u8BFB\u672C\u673A\u6587\u4EF6 / content \u76F4\u4F20\u5168\u6587\u2014\u2014file \u4E0E content\u3001file \u4E0E path \u4E92\u65A5\uFF0Ccontent \u53EF\u4E0E path \u6210\u5BF9\u6216\u5355\u72EC\uFF0C\u5355\u72EC\u65F6\u767B\u8BB0\u503C\u5408\u6210 mcp-inline/<type>\uFF1B\u53EF\u9009 note)\uFF1Brecord-confirm(taskId,node,quote\u2014\u2014\u6682\u505C\u70B9\u7528\u6237\u786E\u8BA4\u539F\u6587\u9010\u5B57)\uFF1Brecord-decision-add(taskId,node,topic,decisionText)\uFF1Brecord-review-set(taskId,node,verdict=pass|fail,rounds,critical)\u3002\u9700\u6C42\u6587\u6863\uFF1Adoc-set(taskId\uFF1Bwhat/why/trackNote \u81F3\u5C11\u4F20\u4E00)\uFF1Bdoc-acceptance-add(taskId,text)\uFF1Bdoc-non-goal-add(taskId,text)\u3002\u7D20\u6750\uFF1Aarchnote-add(taskId,text)\u3002",
     taskArgs,
     async (args) => {
       switch (args.action) {
@@ -2491,15 +2731,27 @@ function createMcpServer() {
           );
         }
         case "context": {
-          const { taskId } = args;
+          const { taskId, view } = args;
           if (taskId === void 0) return requireError("context", ["taskId"], args);
-          return mcpContent(await handleGetContext(client, taskId));
+          if (view !== void 0 && view !== "basic" && view !== "full") {
+            return localError(
+              `action=context \u7684 view \u53EA\u63A5\u53D7 basic|full\uFF08\u6536\u5230 '${view}'\u2014\u2014prompt/skills \u5C5E node action\uFF09`,
+              "view \u503C\u968F action \u4E0D\u540C\uFF1Acontext\u2192basic|full\uFF08\u7F3A\u7701 basic\uFF0C\u4E0D\u643A\u5E26 artifact \u5168\u6587\u5FEB\u7167\uFF09\uFF1Bnode\u2192prompt|skills"
+            );
+          }
+          return mcpContent(await handleGetContext(client, taskId, view));
         }
         case "node": {
           const { taskId, view } = args;
           if (taskId === void 0 || view === void 0) {
             return requireError("node", ["taskId", "view"], args);
           }
+          if (view !== "prompt" && view !== "skills") {
+            return localError(
+              `action=node \u7684 view \u53EA\u63A5\u53D7 prompt|skills\uFF08\u6536\u5230 '${view}'\u2014\u2014basic/full \u5C5E context action\uFF09`,
+              "view \u503C\u968F action \u4E0D\u540C\uFF1Anode\u2192prompt|skills\uFF1Bcontext\u2192basic|full"
+            );
+          }
           let nodeId = args.nodeId;
           if (!nodeId) {
             const q = await handleQueryState(client, taskId);
@@ -2535,6 +2787,11 @@ function createMcpServer() {
           if (taskId === void 0) return requireError("resume", ["taskId"], args);
           return mcpContent(await handleResume(client, taskId, args.resumeNote));
         }
+        case "cancel": {
+          const { taskId } = args;
+          if (taskId === void 0) return requireError("cancel", ["taskId"], args);
+          return mcpContent(await handleCancel(client, taskId, args.reason));
+        }
         case "history": {
           const { taskId } = args;
           if (taskId === void 0) return requireError("history", ["taskId"], args);
@@ -2590,7 +2847,7 @@ function createMcpServer() {
           let fullText = content;
           if (file) {
             try {
-              fullText = readFileSync6(file, "utf-8");
+              fullText = readFileSync7(file, "utf-8");
             } catch (e) {
               return localError(`\u6587\u4EF6\u8BFB\u53D6\u5931\u8D25: ${file}\uFF08${e instanceof Error ? e.message : String(e)}\uFF09`);
             }
@@ -2671,7 +2928,7 @@ function createMcpServer() {
   );
   server.tool(
     "siming_template",
-    "DAG \u6A21\u677F\u7BA1\u7406\u3002action\uFF1Alist=\u6A21\u677F\u5217\u8868\uFF08\u6982\u8981\u6295\u5F71\uFF0C\u4E0D\u542B prompt \u5168\u6587\uFF09\uFF1Bshow=\u6A21\u677F\u8BE6\u60C5\uFF08\u542B\u5168\u90E8\u8282\u70B9 prompt\uFF0C\u4EC5\u5B9E\u9645\u7F16\u6392\u65F6\u7528\uFF09\uFF1Bimport=\u5BFC\u5165\u6A21\u677F\uFF08yaml \u5B57\u7B26\u4E32\u76F4\u4F20\uFF0CprojectId \u7F3A\u7701\u7528 YAML \u5185\u503C\uFF0Cname \u53EF\u8986\u76D6\u6A21\u677F\u540D\uFF09\u3002",
+    "DAG \u6A21\u677F\u7BA1\u7406\u3002action\uFF1Alist=\u6A21\u677F\u5217\u8868\uFF08\u6982\u8981\u6295\u5F71\uFF0C\u4E0D\u542B prompt \u5168\u6587\uFF09\uFF1Bshow=\u6A21\u677F\u8BE6\u60C5\uFF08\u542B\u5168\u90E8\u8282\u70B9 prompt\uFF0C\u4EC5\u5B9E\u9645\u7F16\u6392\u65F6\u7528\uFF09\uFF1Bimport=\u5BFC\u5165\u6A21\u677F\uFF08yaml \u5B57\u7B26\u4E32\u76F4\u4F20\uFF0CprojectId \u7F3A\u7701\u7528 YAML \u5185\u503C\uFF0Cname \u53EF\u8986\u76D6\u6A21\u677F\u540D\uFF09\u3002\u505C\u7528\u6A21\u677F\uFF08Web \u7BA1\u7406\u53F0\u542F\u505C\uFF09\uFF1Alist \u9ED8\u8BA4\u4E0D\u542B\u505C\u7528\u6A21\u677F\uFF1Bshow \u6309 id \u4ECD\u53EF\u8BFB\uFF1B\u7528\u505C\u7528\u6A21\u677F\u521B\u5EFA\u4EFB\u52A1\u88AB\u62D2\uFF08409 TEMPLATE_DISABLED\uFF09\u2014\u2014\u9700\u5728 Web \u7BA1\u7406\u53F0\u91CD\u65B0\u542F\u7528\u540E\u518D\u5EFA\u4EFB\u52A1\u3002",
     templateArgs,
     async (args) => {
       switch (args.action) {
@@ -2711,7 +2968,7 @@ function createMcpServer() {
   );
   server.tool(
     "siming_skill",
-    "skill \u8D44\u4EA7\u7BA1\u7406\u3002action\uFF1Alist\uFF08scope/projectId \u8FC7\u6EE4\uFF09\uFF1Bshow\uFF08name\uFF09\uFF1Bcreate\uFF08name/description/content/category/scope\uFF0Cscope=project \u9700 projectId\uFF09\uFF1Bupdate\uFF08name + \u5F85\u66F4\u65B0\u5B57\u6BB5\uFF0C\u591A\u503C\u5B57\u6BB5\u6574\u4F53\u66FF\u6362\uFF09\uFF1Bcopy\uFF08name/newName/newScope\uFF0CnewScope=project \u9700 targetProjectId\uFF09\uFF1Bdelete\uFF08name\uFF09\u3002",
+    `skill \u8D44\u4EA7\u7BA1\u7406\u3002action\uFF1Alist\uFF08scope/projectId \u8FC7\u6EE4\uFF09\uFF1Bshow\uFF08name\uFF09\uFF1Bcreate\uFF08name/description/content/category/scope\uFF0Cscope=project \u9700 projectId\uFF09\uFF1Bupdate\uFF08name + \u5F85\u66F4\u65B0\u5B57\u6BB5\uFF0C\u591A\u503C\u5B57\u6BB5\u6574\u4F53\u66FF\u6362\uFF09\uFF1Bcopy\uFF08name/newName/newScope\uFF0CnewScope=project \u9700 targetProjectId\uFF09\uFF1Bdelete\uFF08name\uFF09\u3002references\uFF08\u53EF\u9009\uFF09\uFF1A\u5F15\u7528\u6587\u6863\u96C6\u5408 [{path, content}]\u2014\u2014path \u4E3A\u76F8\u5BF9\u8D44\u4EA7\u6839\u7684\u6B63\u659C\u6760\u76F8\u5BF9\u8DEF\u5F84\uFF0C\u7981\u7EDD\u5BF9\u8DEF\u5F84/.. \u56DE\u6EAF/\u53CD\u659C\u6760/\u7A7A\u6BB5/\u4E0E\u4E3B\u6587\u6863\u540D ${"SKILL.md"} \u51B2\u7A81\uFF08\u5927\u5C0F\u5199\u4E0D\u654F\u611F\uFF09/\u8DEF\u5F84\u4E92\u4E3A\u76EE\u5F55\u524D\u7F00\uFF1B\u4E0A\u9650\uFF1A\u5355\u8D44\u4EA7 20 \u6761\u3001\u5355\u6587\u6863 100 \u4E07\u5B57\u7B26\u3001\u4E3B\u6587\u6863+\u5F15\u7528\u603B\u91CF 300 \u4E07\u5B57\u7B26\u3002create \u65F6 references \u5373\u521D\u59CB\u96C6\u5408\uFF1Bupdate \u4E24\u6001\u8BED\u4E49\uFF1A\u7F3A\u7701 references \u4E14 clearRefs \u672A\u4F20 = \u4E0D\u4FEE\u6539\u73B0\u6709\u5F15\u7528\uFF08\u91CD\u8981\uFF1A\u5355\u6587\u4EF6\u66F4\u65B0\u52FF\u4F20 [] \u4EE5\u514D\u8BEF\u6E05\u7A7A\uFF09\u3001references=[] \u6216 clearRefs=true = \u6E05\u7A7A\u5168\u90E8\u3001references=\u975E\u7A7A\u6570\u7EC4 = \u6574\u7B14\u66FF\u6362\uFF1BclearRefs \u4E0E references \u4E92\u65A5\u3002\u5220\u9664\u4FDD\u62A4\uFF1Aupdate \u79FB\u9664\u7684\u5F15\u7528\u6587\u6863 path \u82E5\u4ECD\u51FA\u73B0\u5728\u63D0\u4EA4\u7684\u4E3B\u6587\u6863\u6B63\u6587\u4E2D\uFF0C\u670D\u52A1\u7AEF\u62D2\u7EDD\uFF08409 REFERENCE_IN_USE\uFF09\uFF0C\u9700\u5148\u79FB\u9664\u6B63\u6587\u4E2D\u7684\u5F15\u7528\u518D\u5220\u3002\u505C\u7528\u8D44\u4EA7\uFF08enabled=false\uFF0CWeb \u7BA1\u7406\u53F0\u542F\u505C\uFF09\uFF1Alist \u9ED8\u8BA4\u4E0D\u542B\u505C\u7528\u6761\u76EE\uFF1Bshow\uFF08\u6309\u540D\u5355\u5BFB\u5740\uFF09\u8FD4\u56DE 404\uFF08\u4E0E\u4E0D\u5B58\u5728\u540C\u5F62\uFF09\uFF1Bupdate/delete/copy \u4E0D\u53D7\u542F\u505C\u5F71\u54CD\uFF08\u5199\u901A\u9053\u653E\u884C\uFF0C\u526F\u672C\u9ED8\u8BA4\u542F\u7528\uFF09\uFF1B\u91CD\u65B0\u542F\u7528\u540E\u6062\u590D\u53EF\u89C1\u3002`,
     skillArgs,
     async (args) => {
       switch (args.action) {
@@ -2749,6 +3006,7 @@ function createMcpServer() {
               category,
               scope,
               version: "1.0.0",
+              ...args.references !== void 0 ? { references: args.references } : {},
               ...args.projectId !== void 0 ? { projectId: args.projectId } : {}
             })
           );
@@ -2756,11 +3014,23 @@ function createMcpServer() {
         case "update": {
           const { name } = args;
           if (name === void 0) return requireError("update", ["name"], args);
-          const hasAny = args.description !== void 0 || args.content !== void 0 || args.category !== void 0 || args.version !== void 0 || args.scope !== void 0 || args.projectId !== void 0;
+          if (args.clearRefs === true && args.references !== void 0) {
+            return localError(
+              "action=update \u7684 clearRefs \u4E0E references \u4E92\u65A5",
+              "\u6E05\u7A7A\u5168\u90E8\u5F15\u7528\u6587\u6863\u7528 clearRefs=true \u6216 references=[]\uFF1B\u6574\u7B14\u66FF\u6362\u7528 references=\u5B8C\u6574\u6570\u7EC4"
+            );
+          }
+          let resolvedRefs;
+          if (args.clearRefs === true) {
+            resolvedRefs = [];
+          } else if (args.references !== void 0) {
+            resolvedRefs = args.references;
+          }
+          const hasAny = args.description !== void 0 || args.content !== void 0 || args.category !== void 0 || args.version !== void 0 || args.scope !== void 0 || args.projectId !== void 0 || resolvedRefs !== void 0;
           if (!hasAny) {
             return localError(
-              "action=update \u9700\u8981\u81F3\u5C11\u4E00\u4E2A\u5F85\u66F4\u65B0\u5B57\u6BB5\uFF08description/content/category/version/scope/projectId\uFF09",
-              "\u591A\u503C\u8BED\u4E49\u5B57\u6BB5\u6574\u4F53\u66FF\u6362\uFF0C\u6F0F\u4F20 = \u6E05\u7A7A"
+              "action=update \u9700\u8981\u81F3\u5C11\u4E00\u4E2A\u5F85\u66F4\u65B0\u5B57\u6BB5\uFF08description/content/category/version/scope/projectId/references\uFF09",
+              "\u591A\u503C\u8BED\u4E49\u5B57\u6BB5\u6574\u4F53\u66FF\u6362\uFF1Breferences \u7F3A\u7701 = \u4E0D\u4FEE\u6539\u73B0\u6709\u5F15\u7528"
             );
           }
           return mcpContent(
@@ -2770,6 +3040,7 @@ function createMcpServer() {
               ...args.category !== void 0 ? { category: args.category } : {},
               ...args.version !== void 0 ? { version: args.version } : {},
               ...args.scope !== void 0 ? { scope: args.scope } : {},
+              ...resolvedRefs !== void 0 ? { references: resolvedRefs } : {},
               ...args.projectId !== void 0 ? { projectId: args.projectId } : {}
             })
           );
@@ -2800,7 +3071,7 @@ function createMcpServer() {
   );
   server.tool(
     "siming_agent",
-    "agent \u8D44\u4EA7\u7BA1\u7406\u3002action\uFF1Alist\uFF08scope/projectId \u8FC7\u6EE4\uFF09\uFF1Bshow\uFF08name\uFF09\uFF1Bcreate\uFF08name/description/systemPrompt/model/scope\uFF0Cscope=project \u9700 projectId\uFF1BboundSkills/tools/permissions \u53EF\u9009\uFF09\uFF1Bupdate\uFF08name + \u5F85\u66F4\u65B0\u5B57\u6BB5\uFF0CboundSkills/tools/permissions \u4E3A\u6574\u4F53\u66FF\u6362\u8BED\u4E49\uFF09\uFF1Bcopy\uFF08name/newName/newScope\uFF0CnewScope=project \u9700 targetProjectId\uFF09\uFF1Bdelete\uFF08name\uFF09\u3002\u5168\u5C40 agent \u4EC5\u53EF\u7ED1\u5B9A\u5168\u5C40 skill\u3002tools/permissions \u4E3A\u5B57\u7B26\u4E32\u6570\u7EC4\u3001\u65E0\u670D\u52A1\u7AEF\u503C\u57DF\u6821\u9A8C\u2014\u2014\u8BED\u4E49\u662F\u8D44\u4EA7\u5B89\u88C5\u5230\u7F16\u7A0B\u5DE5\u5177\u65F6\u5EFA\u8BAE\u6388\u4E88\u8BE5 agent \u7684\u5DE5\u5177\u540D/\u6743\u9650\u6E05\u5355\uFF0C\u7531\u5BBF\u4E3B\u4FA7\u89E3\u91CA\uFF1Bmodel \u987B\u4E3A\u5DF2\u6CE8\u518C model alias code\uFF08\u53EF\u7528\u503C\u7ECF model \u6620\u5C04\u7BA1\u7406\uFF0C\u672A\u6CE8\u518C\u521B\u5EFA\u88AB\u62D2\uFF09\u3002",
+    `agent \u8D44\u4EA7\u7BA1\u7406\u3002action\uFF1Alist\uFF08scope/projectId \u8FC7\u6EE4\uFF09\uFF1Bshow\uFF08name\uFF09\uFF1Bcreate\uFF08name/description/systemPrompt/model/scope\uFF0Cscope=project \u9700 projectId\uFF1BboundSkills/tools/permissions \u53EF\u9009\uFF09\uFF1Bupdate\uFF08name + \u5F85\u66F4\u65B0\u5B57\u6BB5\uFF0CboundSkills/tools/permissions \u4E3A\u6574\u4F53\u66FF\u6362\u8BED\u4E49\uFF09\uFF1Bcopy\uFF08name/newName/newScope\uFF0CnewScope=project \u9700 targetProjectId\uFF09\uFF1Bdelete\uFF08name\uFF09\u3002\u5168\u5C40 agent \u4EC5\u53EF\u7ED1\u5B9A\u5168\u5C40 skill\u3002function\uFF08\u53EF\u9009\uFF09\uFF1Areviewer|executor\uFF0C\u7F3A\u7701 executor\uFF08T202608260002\uFF09\u2014\u2014\u529F\u80FD\u7C7B\u578B\u4EC5\u5F71\u54CD siming install \u843D\u76D8\u7684\u4FE1\u606F\u8FB9\u754C\u6CE8\u5165\uFF1Areviewer \u843D\u76D8\u4EA7\u7269\u6B63\u6587\u5934\u6CE8\u5165\u53D7\u9650\u4F9D\u636E\u58F0\u660E\uFF0Cexecutor \u4E0D\u6CE8\u5165\uFF1Bfunction \u53D8\u66F4\u65F6\u670D\u52A1\u7AEF\u81EA\u52A8\u9012\u589E\u7248\u672C\u4EE5\u4F20\u64AD\u5DF2\u88C5\u73AF\u5883\u3002tools/permissions \u4E3A\u5B57\u7B26\u4E32\u6570\u7EC4\u3001\u65E0\u670D\u52A1\u7AEF\u503C\u57DF\u6821\u9A8C\u2014\u2014\u8BED\u4E49\u662F\u8D44\u4EA7\u5B89\u88C5\u5230\u7F16\u7A0B\u5DE5\u5177\u65F6\u5EFA\u8BAE\u6388\u4E88\u8BE5 agent \u7684\u5DE5\u5177\u540D/\u6743\u9650\u6E05\u5355\uFF0C\u7531\u5BBF\u4E3B\u4FA7\u89E3\u91CA\uFF1Bmodel \u987B\u4E3A\u5DF2\u6CE8\u518C model alias code\uFF08\u53EF\u7528\u503C\u7ECF model \u6620\u5C04\u7BA1\u7406\uFF0C\u672A\u6CE8\u518C\u521B\u5EFA\u88AB\u62D2\uFF09\u3002references\uFF08\u53EF\u9009\uFF09\uFF1A\u5F15\u7528\u6587\u6863\u96C6\u5408 [{path, content}]\u2014\u2014path \u4E3A\u76F8\u5BF9\u8D44\u4EA7\u6839\u7684\u6B63\u659C\u6760\u76F8\u5BF9\u8DEF\u5F84\uFF0C\u7981\u7EDD\u5BF9\u8DEF\u5F84/.. \u56DE\u6EAF/\u53CD\u659C\u6760/\u7A7A\u6BB5/\u4E0E\u4E3B\u6587\u6863\u540D ${"agent.md"} \u51B2\u7A81\uFF08\u5927\u5C0F\u5199\u4E0D\u654F\u611F\uFF09/\u8DEF\u5F84\u4E92\u4E3A\u76EE\u5F55\u524D\u7F00\uFF1B\u4E0A\u9650\uFF1A\u5355\u8D44\u4EA7 20 \u6761\u3001\u5355\u6587\u6863 100 \u4E07\u5B57\u7B26\u3001\u4E3B\u6587\u6863+\u5F15\u7528\u603B\u91CF 300 \u4E07\u5B57\u7B26\u3002create \u65F6 references \u5373\u521D\u59CB\u96C6\u5408\uFF1Bupdate \u4E24\u6001\u8BED\u4E49\uFF1A\u7F3A\u7701 references \u4E14 clearRefs \u672A\u4F20 = \u4E0D\u4FEE\u6539\u73B0\u6709\u5F15\u7528\u3001references=[] \u6216 clearRefs=true = \u6E05\u7A7A\u5168\u90E8\u3001references=\u975E\u7A7A\u6570\u7EC4 = \u6574\u7B14\u66FF\u6362\uFF1BclearRefs \u4E0E references \u4E92\u65A5\u3002\u5220\u9664\u4FDD\u62A4\uFF1Aupdate \u79FB\u9664\u7684\u5F15\u7528\u6587\u6863 path \u82E5\u4ECD\u51FA\u73B0\u5728\u63D0\u4EA4\u7684 systemPrompt \u6B63\u6587\u4E2D\uFF0C\u670D\u52A1\u7AEF\u62D2\u7EDD\uFF08409 REFERENCE_IN_USE\uFF09\uFF0C\u9700\u5148\u79FB\u9664\u6B63\u6587\u4E2D\u7684\u5F15\u7528\u518D\u5220\u3002\u505C\u7528\u8D44\u4EA7\uFF08enabled=false\uFF0CWeb \u7BA1\u7406\u53F0\u542F\u505C\uFF09\uFF1Alist \u9ED8\u8BA4\u4E0D\u542B\u505C\u7528\u6761\u76EE\uFF1Bshow\uFF08\u6309\u540D\u5355\u5BFB\u5740\uFF09\u8FD4\u56DE 404\uFF08\u4E0E\u4E0D\u5B58\u5728\u540C\u5F62\uFF09\uFF1Bupdate/delete/copy \u4E0D\u53D7\u542F\u505C\u5F71\u54CD\uFF08\u5199\u901A\u9053\u653E\u884C\uFF0C\u526F\u672C\u9ED8\u8BA4\u542F\u7528\uFF09\uFF1B\u91CD\u65B0\u542F\u7528\u540E\u6062\u590D\u53EF\u89C1\u3002`,
     agentArgs,
     async (args) => {
       switch (args.action) {
@@ -2838,9 +3109,12 @@ function createMcpServer() {
               model,
               scope,
               version: "1.0.0",
+              // function 缺省 executor（AgentCreate 输出类型必有，与 API 缺省归一一致）
+              "function": args["function"] ?? "executor",
               boundSkills: args.boundSkills ?? [],
               tools: args.tools ?? [],
               permissions: args.permissions ?? [],
+              ...args.references !== void 0 ? { references: args.references } : {},
               ...args.projectId !== void 0 ? { projectId: args.projectId } : {}
             })
           );
@@ -2848,11 +3122,23 @@ function createMcpServer() {
         case "update": {
           const { name } = args;
           if (name === void 0) return requireError("update", ["name"], args);
-          const hasAny = args.description !== void 0 || args.systemPrompt !== void 0 || args.model !== void 0 || args.scope !== void 0 || args.projectId !== void 0 || args.boundSkills !== void 0 || args.tools !== void 0 || args.permissions !== void 0;
+          if (args.clearRefs === true && args.references !== void 0) {
+            return localError(
+              "action=update \u7684 clearRefs \u4E0E references \u4E92\u65A5",
+              "\u6E05\u7A7A\u5168\u90E8\u5F15\u7528\u6587\u6863\u7528 clearRefs=true \u6216 references=[]\uFF1B\u6574\u7B14\u66FF\u6362\u7528 references=\u5B8C\u6574\u6570\u7EC4"
+            );
+          }
+          let resolvedRefs;
+          if (args.clearRefs === true) {
+            resolvedRefs = [];
+          } else if (args.references !== void 0) {
+            resolvedRefs = args.references;
+          }
+          const hasAny = args.description !== void 0 || args.systemPrompt !== void 0 || args.model !== void 0 || args.scope !== void 0 || args.projectId !== void 0 || args.boundSkills !== void 0 || args.tools !== void 0 || args.permissions !== void 0 || args["function"] !== void 0 || resolvedRefs !== void 0;
           if (!hasAny) {
             return localError(
-              "action=update \u9700\u8981\u81F3\u5C11\u4E00\u4E2A\u5F85\u66F4\u65B0\u5B57\u6BB5\uFF08description/systemPrompt/model/scope/projectId/boundSkills/tools/permissions\uFF09",
-              "boundSkills/tools/permissions \u4E3A\u6574\u4F53\u66FF\u6362\u8BED\u4E49\uFF0C\u6F0F\u4F20 = \u6E05\u7A7A"
+              "action=update \u9700\u8981\u81F3\u5C11\u4E00\u4E2A\u5F85\u66F4\u65B0\u5B57\u6BB5\uFF08description/systemPrompt/model/scope/projectId/boundSkills/tools/permissions/function/references\uFF09",
+              "boundSkills/tools/permissions \u4E3A\u6574\u4F53\u66FF\u6362\u8BED\u4E49\uFF0C\u6F0F\u4F20 = \u6E05\u7A7A\uFF1Breferences \u7F3A\u7701 = \u4E0D\u4FEE\u6539\u73B0\u6709\u5F15\u7528"
             );
           }
           return mcpContent(
@@ -2864,7 +3150,9 @@ function createMcpServer() {
               ...args.projectId !== void 0 ? { projectId: args.projectId } : {},
               ...args.boundSkills !== void 0 ? { boundSkills: args.boundSkills } : {},
               ...args.tools !== void 0 ? { tools: args.tools } : {},
-              ...args.permissions !== void 0 ? { permissions: args.permissions } : {}
+              ...args.permissions !== void 0 ? { permissions: args.permissions } : {},
+              ...args["function"] !== void 0 ? { "function": args["function"] } : {},
+              ...resolvedRefs !== void 0 ? { references: resolvedRefs } : {}
             })
           );
         }
@@ -3013,7 +3301,7 @@ function createMcpServer() {
   );
   server.tool(
     "siming_export",
-    "\u4ECE\u672C\u5730\u8D44\u4EA7\u6761\u76EE\u5BFC\u51FA\u5230 Siming server\uFF0C\u4E24\u9636\u6BB5\uFF1Aaction=plan \u751F\u6210\u8BA1\u5212\uFF08\u4E0D\u5199\u5165\uFF0C\u8FD4\u56DE created/updated/skipped/error \u5224\u5B9A\uFF09\uFF0Caction=apply \u6267\u884C\u8BA1\u5212\u3002entries \u4E3A JSON \u5B57\u7B26\u4E32\uFF0C\u9876\u5C42 {skipExisting?, skills?: [...], agents?: [...], dags?: [...]}\uFF08skipExisting \u7F3A\u7701 false\u2014\u2014server \u5DF2\u6709\u540C\u540D\u8D44\u4EA7\u65F6\u8DF3\u8FC7\uFF0C\u6761\u76EE\u7EA7\u53EF\u8986\u76D6\uFF09\u3002\u6761\u76EE\u5B57\u6BB5\u2014\u2014skill\uFF1A\u5FC5\u586B name\u3001content\uFF08SKILL \u6B63\u6587\uFF0C\u4E0D\u542B frontmatter\uFF09\uFF1B\u53EF\u9009 description\u3001category\uFF08\u7F3A\u7701 process\uFF09\u3001version\uFF08\u7F3A\u7701 1.0.0\uFF09\u3001scope\uFF08\u7F3A\u7701 global\uFF1Bproject \u987B projectKey\uFF09\u3002agent\uFF1A\u5FC5\u586B name\u3001systemPrompt\u3001model\uFF08\u987B\u4E3A\u5DF2\u6CE8\u518C model alias code\uFF09\uFF1B\u53EF\u9009 description\u3001boundSkills[]\u3001tools[]\u3001permissions[]\u3001version\u3001scope+projectKey\u3002dag\uFF1A\u5FC5\u586B projectKey\u3001nodes\u3001edges\uFF1B\u5176\u4F59\u5B57\u6BB5\u540C DAG \u6A21\u677F\u7ED3\u6784\uFF08name/description/edge pausePoint \u7B49\uFF09\u3002\u7248\u672C\u5224\u5B9A\uFF1Aserver \u65E0\u540C\u540D\u2192created\uFF1BskipExisting \u547D\u4E2D\u2192skipped\uFF1Bversion\u2260\u73B0\u503C\u2192updated\uFF1Bversion \u76F8\u540C\u2192\u5185\u5BB9\u8986\u76D6+\u672B\u4F4D patch+1\uFF08\u5185\u5BB9\u76F8\u540C\u4E0D\u9012\u589E\uFF09\u3002types \u8FC7\u6EE4\u6761\u76EE\u7C7B\u578B\uFF1Bonly \u6307\u5B9A\u5355\u6761\u91CD\u8BD5\u3002",
+    "\u4ECE\u672C\u5730\u8D44\u4EA7\u6761\u76EE\u5BFC\u51FA\u5230 Siming server\uFF0C\u4E24\u9636\u6BB5\uFF1Aaction=plan \u751F\u6210\u8BA1\u5212\uFF08\u4E0D\u5199\u5165\uFF0C\u8FD4\u56DE created/updated/skipped/error \u5224\u5B9A\uFF09\uFF0Caction=apply \u6267\u884C\u8BA1\u5212\u3002entries \u4E3A JSON \u5B57\u7B26\u4E32\uFF0C\u9876\u5C42 {skipExisting?, skills?: [...], agents?: [...], dags?: [...]}\uFF08skipExisting \u7F3A\u7701 false\u2014\u2014server \u5DF2\u6709\u540C\u540D\u8D44\u4EA7\u65F6\u8DF3\u8FC7\uFF0C\u6761\u76EE\u7EA7\u53EF\u8986\u76D6\uFF09\u3002\u6761\u76EE\u5B57\u6BB5\u2014\u2014skill\uFF1A\u5FC5\u586B name\u3001content\uFF08SKILL \u6B63\u6587\uFF0C\u4E0D\u542B frontmatter\uFF09\uFF1B\u53EF\u9009 description\u3001category\uFF08\u7F3A\u7701 process\uFF09\u3001version\uFF08\u7F3A\u7701 1.0.0\uFF09\u3001scope\uFF08\u7F3A\u7701 global\uFF1Bproject \u987B projectKey\uFF09\u3001references\u3002agent\uFF1A\u5FC5\u586B name\u3001systemPrompt\u3001model\uFF08\u987B\u4E3A\u5DF2\u6CE8\u518C model alias code)\uFF1B\u53EF\u9009 description\u3001boundSkills[]\u3001tools[]\u3001permissions[]\u3001version\u3001scope+projectKey\u3001references\u3002references \u4E24\u6001\u8BED\u4E49\uFF08skill/agent \u540C\uFF09\uFF1A\u6761\u76EE\u7F3A references \u952E = \u4E0D\u4FEE\u6539 server \u73B0\u6709\u5F15\u7528\uFF08\u5355\u6587\u4EF6\u6761\u76EE\u4FDD\u6301\u7F3A\u7701\u5373\u96F6\u5F71\u54CD\uFF09\u3001\u663E\u5F0F [] = \u6E05\u7A7A\u5168\u90E8\u5F15\u7528\u3001\u975E\u7A7A\u6570\u7EC4 = \u6574\u7B14\u66FF\u6362\uFF1B\u5143\u7D20\u7ED3\u6784 [{path, content}]\uFF0Cpath \u4E3A\u76F8\u5BF9\u8D44\u4EA7\u6839\u7684\u6B63\u659C\u6760\u76F8\u5BF9\u8DEF\u5F84\uFF08\u7981\u7EDD\u5BF9\u8DEF\u5F84/../\u53CD\u659C\u6760/\u4E0E\u4E3B\u6587\u6863\u540D SKILL.md|agent.md \u51B2\u7A81/\u4E92\u4E3A\u76EE\u5F55\u524D\u7F00\uFF09\uFF0C\u4E0A\u9650\u5355\u8D44\u4EA7 20 \u6761\u3001\u5355\u6587\u6863 100 \u4E07\u5B57\u7B26\u3001\u4E3B\u6587\u6863+\u5F15\u7528\u603B\u91CF 300 \u4E07\u5B57\u7B26\u2014\u2014plan \u671F\u9884\u68C0\u975E\u6CD5\u6216\u8D85\u805A\u5408\u4E0A\u9650\u5373\u6807 error\uFF0C\u4E0D\u8FDB\u5165 apply\u3002dag\uFF1A\u5FC5\u586B projectKey\u3001nodes\u3001edges\uFF1B\u5176\u4F59\u5B57\u6BB5\u540C DAG \u6A21\u677F\u7ED3\u6784\uFF08name/description/edge pausePoint \u7B49\uFF09\u3002\u7248\u672C\u5224\u5B9A\uFF1Aserver \u65E0\u540C\u540D\u2192created\uFF1BskipExisting \u547D\u4E2D\u2192skipped\uFF1Bversion\u2260\u73B0\u503C\u2192updated\uFF1Bversion \u76F8\u540C\u2192\u5185\u5BB9\u8986\u76D6+\u672B\u4F4D patch+1\uFF08\u5185\u5BB9\u76F8\u540C\u4E0D\u9012\u589E\uFF09\u3002types \u8FC7\u6EE4\u6761\u76EE\u7C7B\u578B\uFF1Bonly \u6307\u5B9A\u5355\u6761\u91CD\u8BD5\u3002",
     exportArgs,
     async (args) => {
       let parsed;
@@ -3045,7 +3333,7 @@ function createMcpServer() {
   );
   server.tool(
     "siming_install",
-    "\u4ECE Siming server \u4E0B\u53D1\u8D44\u4EA7\u5230\u672C\u5730 .agents \u5F00\u653E\u534F\u8BAE\u901A\u7528\u843D\u70B9\uFF0C\u4E24\u9636\u6BB5\uFF1Aaction=plan \u751F\u6210\u5B89\u88C5\u8BA1\u5212\uFF08\u4E0D\u5199\u5165\uFF0C\u8FD4\u56DE install/update/skip/conflict \u5224\u5B9A\uFF09\uFF0Caction=apply \u6267\u884C\u5199\u5165\u3002scope=global \u5199\u5165 ~/.agents/\uFF08skills/\u3001agents/\u3001mcp.json\u2014\u2014MCP \u6CE8\u518C\u8FDB\u9876\u5C42 mcpServers.siming \u6761\u76EE\uFF0CSIMING_AGENTS_HOME \u53EF\u8986\u76D6\u6839\u76EE\u5F55\uFF09\uFF0Cscope=project \u5199\u5165\u5F53\u524D\u5DE5\u4F5C\u533A .agents/\uFF08\u9700\u5148\u7ED1\u5B9A\u9879\u76EE\uFF0C\u4E0D\u542B MCP \u6CE8\u518C\uFF09\u3002\u4E0D\u5199\u5165\u4EFB\u4F55\u7F16\u7A0B\u5DE5\u5177\u79C1\u6709\u76EE\u5F55\u3002force \u8986\u76D6\u6240\u6709\u9009\u4E2D\u7684\u672C\u5730\u8D44\u4EA7\uFF0C\u5305\u62EC\u76F8\u540C\u7248\u672C\u548C\u51B2\u7A81\u9879\uFF1Byes \u8DF3\u8FC7\u4EA4\u4E92\u786E\u8BA4\u3002apply \u8FD4\u56DE guidance \u8FC1\u79FB\u6307\u5F15\uFF08\u5168\u90E8\u8DF3\u8FC7\u7684\u5E42\u7B49\u91CD\u88C5\u540C\u6837\u8FD4\u56DE\uFF09\uFF0C\u4F9B\u5F53\u524D\u7F16\u7A0B\u5DE5\u5177\u4F1A\u8BDD\u4E2D\u7684 AI \u628A\u901A\u7528\u8D44\u4EA7\u6CE8\u518C\u5230\u672C\u5DE5\u5177\u81EA\u5DF1\u7684\u914D\u7F6E\u3002",
+    "\u4ECE Siming server \u4E0B\u53D1\u8D44\u4EA7\u5230\u672C\u5730 .agents \u5F00\u653E\u534F\u8BAE\u901A\u7528\u843D\u70B9\uFF0C\u4E24\u9636\u6BB5\uFF1Aaction=plan \u751F\u6210\u5B89\u88C5\u8BA1\u5212\uFF08\u4E0D\u5199\u5165\uFF0C\u8FD4\u56DE install/update/skip/conflict \u5224\u5B9A\uFF09\uFF0Caction=apply \u6267\u884C\u5199\u5165\u3002scope=global \u5199\u5165 ~/.agents/\uFF08skills/\u3001agents/\u3001mcp.json\u2014\u2014MCP \u6CE8\u518C\u8FDB\u9876\u5C42 mcpServers.siming \u6761\u76EE\uFF0CSIMING_AGENTS_HOME \u53EF\u8986\u76D6\u6839\u76EE\u5F55\uFF09\uFF0Cscope=project \u5199\u5165\u5F53\u524D\u5DE5\u4F5C\u533A .agents/\uFF08\u9700\u5148\u7ED1\u5B9A\u9879\u76EE\uFF0C\u4E0D\u542B MCP \u6CE8\u518C\uFF09\u3002\u4E0D\u5199\u5165\u4EFB\u4F55\u7F16\u7A0B\u5DE5\u5177\u79C1\u6709\u76EE\u5F55\u3002force \u8986\u76D6\u6240\u6709\u9009\u4E2D\u7684\u672C\u5730\u8D44\u4EA7\uFF0C\u5305\u62EC\u76F8\u540C\u7248\u672C\u548C\u51B2\u7A81\u9879\uFF08\u4F8B\u5916\uFF1Aserver \u505C\u7528\u8D44\u4EA7\u6052 skip\u3001force \u4EA6\u4E0D\u843D\u76D8\uFF0C\u8BA1\u5212 reason \u6807\u6CE8 server asset disabled\uFF0C\u672C\u5730\u5DF2\u88C5\u6587\u4EF6\u4E0D\u53D7\u5F71\u54CD\u4E0D\u5220\u9664\uFF09\uFF1Byes \u8DF3\u8FC7\u4EA4\u4E92\u786E\u8BA4\u3002apply \u8FD4\u56DE guidance \u8FC1\u79FB\u6307\u5F15\uFF08\u5168\u90E8\u8DF3\u8FC7\u7684\u5E42\u7B49\u91CD\u88C5\u540C\u6837\u8FD4\u56DE\uFF09\uFF0C\u4F9B\u5F53\u524D\u7F16\u7A0B\u5DE5\u5177\u4F1A\u8BDD\u4E2D\u7684 AI \u628A\u901A\u7528\u8D44\u4EA7\u6CE8\u518C\u5230\u672C\u5DE5\u5177\u81EA\u5DF1\u7684\u914D\u7F6E\u3002",
     installArgs,
     async (args) => {
       const scope = args.scope ?? "global";
@@ -3156,13 +3444,17 @@ async function mcpServeCommand() {
 
 // src/commands/task/command.ts
 import { Command as Command5 } from "commander";
-import { readFileSync as readFileSync7 } from "fs";
+import { readFileSync as readFileSync8 } from "fs";
 import { z as z5 } from "zod";
-import { ARTIFACT_TYPES as ARTIFACT_TYPES2, TASK_TYPES as TASK_TYPES2 } from "@siming-org/core";
+import {
+  ARTIFACT_TYPES as ARTIFACT_TYPES2,
+  TASK_TYPES as TASK_TYPES2,
+  ContextViewSchema
+} from "@siming-org/core";
 var PAGE_DEFAULT = 20;
 var PAGE_MAX = 500;
 function createTaskCommand() {
-  const task = new Command5("task").description("Task management \u2014 create, advance, approve, pause, resume, query");
+  const task = new Command5("task").description("Task management \u2014 create, advance, approve, pause, resume, cancel, query");
   withCommonOpts(task.command("list"), "table").option("--status <s>", "filter by status").option("--track <t>", "filter by track").option("--project <key-or-id>", "filter by projectId (key or id)").option("--page <n>", "page number (default 1)", "1").option("--limit <n>", `page size (default ${PAGE_DEFAULT}, max ${PAGE_MAX})`).option("--all", `show all (limit ${PAGE_MAX})`).option("--sort <s>", "sort: progress|createdAt|updatedAt (default progress)").description("List tasks (summary projection: no dagInstance/history payloads)").action(async (opts) => {
     const client = createClient(opts.url);
     const filters = {};
@@ -3319,9 +3611,18 @@ function createTaskCommand() {
     const result = await handleApprove(client, taskId, decisionR.data, opts.comment);
     renderResult(opts.format, result);
   });
-  withCommonOpts(task.command("context <taskId>"), "fancy").description("One-stop context for advancing: current node prompt, node states, pending pause edge, task doc background").action(async (taskId, opts) => {
+  withCommonOpts(task.command("context <taskId>"), "fancy").description("One-stop context for advancing: current node prompt, node states, pending pause edge, task doc background").option("--view <v>", "basic\uFF08\u9ED8\u8BA4\uFF1A\u4E0D\u643A\u5E26 artifact \u5168\u6587\u5FEB\u7167\uFF09| full\uFF08\u65AD\u70B9\u7EED\u8DD1\u9700\u5386\u53F2\u4EA7\u7269\u5168\u6587\u65F6\u7528\uFF0C\u4E0E\u5168\u91CF\u5F62\u6001\u7B49\u4EF7\uFF09").action(async (taskId, opts) => {
+    let view;
+    if (opts.view !== void 0) {
+      const viewR = parseEnum(opts.view, ContextViewSchema, "view");
+      if (!viewR.success) {
+        renderResult(opts.format, viewR);
+        return;
+      }
+      view = viewR.data;
+    }
     const client = createClient(opts.url);
-    const result = await handleGetContext(client, taskId);
+    const result = await handleGetContext(client, taskId, view);
     renderResult(opts.format, result, { fields: result.success ? contextFields(result.data) : [] });
   });
   const doc = task.command("doc").description("Structured task doc \u2014 what/why/acceptance/non-goals (stored in siming DB)");
@@ -3352,7 +3653,7 @@ function createTaskCommand() {
     const client = createClient(opts.url);
     const result = await handleDocAcceptanceAdd(client, taskId, opts.text);
     if (result.success) {
-      renderResult(opts.format, result, { successMessage: `${taskId} acceptance \u5DF2\u6DFB\u52A0\uFF08\u5171 ${(result.data.doc?.acceptance ?? []).length} \u6761\uFF09` });
+      renderResult(opts.format, result, { successMessage: `${taskId} acceptance \u5DF2\u6DFB\u52A0` });
     } else {
       renderResult(opts.format, result);
     }
@@ -3362,7 +3663,7 @@ function createTaskCommand() {
     const client = createClient(opts.url);
     const result = await handleDocNonGoalAdd(client, taskId, opts.text);
     if (result.success) {
-      renderResult(opts.format, result, { successMessage: `${taskId} non-goal \u5DF2\u6DFB\u52A0\uFF08\u5171 ${(result.data.doc?.nonGoals ?? []).length} \u6761\uFF09` });
+      renderResult(opts.format, result, { successMessage: `${taskId} non-goal \u5DF2\u6DFB\u52A0` });
     } else {
       renderResult(opts.format, result);
     }
@@ -3377,6 +3678,11 @@ function createTaskCommand() {
     const result = await handleResume(client, taskId, opts.decision);
     renderResult("json", result);
   });
+  task.command("cancel <taskId>").description("Cancel a task (active/paused \u2192 cancelled terminal state, irreversible)").option("--url <url>", "server base URL").option("--reason <text>", "cancel reason (1-500 chars)").action(async (taskId, opts) => {
+    const client = createClient(opts.url);
+    const result = await handleCancel(client, taskId, opts.reason);
+    renderResult("json", result);
+  });
   task.command("history <taskId>").description("Show task node history").option("--url <url>", "server base URL").option("--format <fmt>", "output format", "table").action(async (taskId, opts) => {
     const client = createClient(opts.url);
     const result = await handleGetHistory(client, taskId);
@@ -3408,9 +3714,7 @@ function createTaskCommand() {
     const client = createClient(opts.url);
     const result = await handleRecordCheckAdd(client, taskId, opts.node, opts.item, !opts.failed);
     if (result.success) {
-      const checks = (result.data.nodeRecords ?? {})[opts.node]?.checks ?? [];
-      const last = checks[checks.length - 1];
-      renderResult(opts.format, result, { successMessage: `${taskId} \u8282\u70B9 ${opts.node} check \u5DF2\u6DFB\u52A0\uFF08\u5171 ${checks.length} \u6761\uFF0C\u65B0\u6761\u76EE id ${last?.id ?? "?"}\uFF09` });
+      renderResult(opts.format, result, { successMessage: `${taskId} \u8282\u70B9 ${opts.node} check \u5DF2\u6DFB\u52A0\uFF08\u65B0\u6761\u76EE id ${result.data.entry?.id ?? "?"}\uFF09` });
     } else {
       renderResult(opts.format, result);
     }
@@ -3443,7 +3747,7 @@ function createTaskCommand() {
     let content;
     if (opts.file) {
       try {
-        content = readFileSync7(opts.file, "utf-8");
+        content = readFileSync8(opts.file, "utf-8");
       } catch (e) {
         renderResult(opts.format, fail({ message: `\u6587\u4EF6\u8BFB\u53D6\u5931\u8D25: ${opts.file}\uFF08${e instanceof Error ? e.message : String(e)}\uFF09`, httpStatus: 0 }));
         return;
@@ -3457,8 +3761,7 @@ function createTaskCommand() {
     const client = createClient(opts.url);
     const result = await handleRecordArtifactAdd(client, taskId, opts.node, typeR.data, path, opts.note, content);
     if (result.success) {
-      const artifacts = (result.data.nodeRecords ?? {})[opts.node]?.artifacts ?? [];
-      renderResult(opts.format, result, { successMessage: `${taskId} \u8282\u70B9 ${opts.node} artifact \u5DF2\u6DFB\u52A0\uFF08\u5171 ${artifacts.length} \u6761\uFF1A${typeR.data} ${path}${content !== void 0 ? "\uFF08\u542B\u5168\u6587\u5FEB\u7167 " + content.length + " \u5B57\u7B26\uFF09" : ""}\uFF09` });
+      renderResult(opts.format, result, { successMessage: `${taskId} \u8282\u70B9 ${opts.node} artifact \u5DF2\u6DFB\u52A0\uFF08\u65B0\u6761\u76EE id ${result.data.entry?.id ?? "?"}\uFF1A${typeR.data} ${path}${content !== void 0 ? "\uFF08\u542B\u5168\u6587\u5FEB\u7167 " + content.length + " \u5B57\u7B26\uFF09" : ""}\uFF09` });
     } else {
       renderResult(opts.format, result);
     }
@@ -3467,8 +3770,7 @@ function createTaskCommand() {
     const client = createClient(opts.url);
     const result = await handleRecordConfirmAdd(client, taskId, opts.node, opts.quote);
     if (result.success) {
-      const confirmations = (result.data.nodeRecords ?? {})[opts.node]?.confirmations ?? [];
-      renderResult(opts.format, result, { successMessage: `${taskId} \u8282\u70B9 ${opts.node} \u786E\u8BA4\u539F\u6587\u5DF2\u8BB0\u5F55\uFF08\u5171 ${confirmations.length} \u6761\uFF09` });
+      renderResult(opts.format, result, { successMessage: `${taskId} \u8282\u70B9 ${opts.node} \u786E\u8BA4\u539F\u6587\u5DF2\u8BB0\u5F55\uFF08\u65B0\u6761\u76EE id ${result.data.entry?.id ?? "?"}\uFF09` });
     } else {
       renderResult(opts.format, result);
     }
@@ -3478,8 +3780,7 @@ function createTaskCommand() {
     const client = createClient(opts.url);
     const result = await handleRecordDecisionAdd(client, taskId, opts.node, opts.topic, opts.decision);
     if (result.success) {
-      const decisions = (result.data.nodeRecords ?? {})[opts.node]?.decisions ?? [];
-      renderResult(opts.format, result, { successMessage: `${taskId} \u8282\u70B9 ${opts.node} \u51B3\u7B56\u5DF2\u8BB0\u5F55\uFF08\u5171 ${decisions.length} \u6761\uFF1A${opts.topic}\uFF09` });
+      renderResult(opts.format, result, { successMessage: `${taskId} \u8282\u70B9 ${opts.node} \u51B3\u7B56\u5DF2\u8BB0\u5F55\uFF08\u65B0\u6761\u76EE id ${result.data.entry?.id ?? "?"}\uFF1A${opts.topic}\uFF09` });
     } else {
       renderResult(opts.format, result);
     }
@@ -3518,7 +3819,7 @@ function createTaskCommand() {
     const client = createClient(opts.url);
     const result = await handleArchNoteAdd(client, taskId, opts.text);
     if (result.success) {
-      renderResult(opts.format, result, { successMessage: `${taskId} \u7D2F\u79EF\u7D20\u6750\u5DF2\u6DFB\u52A0\uFF08\u5171 ${(result.data.archNotes ?? []).length} \u6761\uFF09` });
+      renderResult(opts.format, result, { successMessage: `${taskId} \u7D2F\u79EF\u7D20\u6750\u5DF2\u6DFB\u52A0\uFF08\u65B0\u6761\u76EE id ${result.data.entry?.id ?? "?"}\uFF09` });
     } else {
       renderResult(opts.format, result);
     }
@@ -3629,7 +3930,7 @@ function progressText(row) {
 
 // src/commands/skill/command.ts
 import { Command as Command6 } from "commander";
-import { SkillScopeSchema as SkillScopeSchema2 } from "@siming-org/core";
+import { SKILL_MAIN_DOC as SKILL_MAIN_DOC4, SkillScopeSchema as SkillScopeSchema2 } from "@siming-org/core";
 function createSkillCommand() {
   const skill = new Command6("skill").description("Skill management \u2014 global/project-scoped skills");
   withCommonOpts(skill.command("list"), "table").option("--project <id>", "filter by projectId").description("List skills").action(async (opts) => {
@@ -3641,6 +3942,7 @@ function createSkillCommand() {
         { key: "category", header: "Category" },
         { key: "scope", header: "Scope" },
         { key: "version", header: "Version" },
+        { key: "referenceCount", header: "Refs" },
         { key: "description", header: "Description", maxWidth: 40 }
       ]
     });
@@ -3650,7 +3952,7 @@ function createSkillCommand() {
     const result = await handleGetSkill(client, name);
     renderResult(opts.format, result, { fields: result.success ? skillFields(result.data) : [] });
   });
-  skill.command("create").description("Create a skill (scope required)").option("--url <url>", "server base URL").requiredOption("--name <name>", "skill name (kebab-case)").requiredOption("--description <text>", "skill description").requiredOption("--content <text>", "skill content (prompt body)").requiredOption("--category <cat>", "process|domain|tooling").requiredOption("--scope <scope>", "global|project").option("--project-id <hex>", "projectId (required when scope=project)").action(async (opts) => {
+  skill.command("create").description("Create a skill (scope required)").option("--url <url>", "server base URL").requiredOption("--name <name>", "skill name (kebab-case)").requiredOption("--description <text>", "skill description").requiredOption("--content <text>", "skill content (prompt body)").requiredOption("--category <cat>", "process|domain|tooling").requiredOption("--scope <scope>", "global|project").option("--ref <path@file>", "reference doc: <relative path>@<local file> (repeatable)", collectArgs, []).option("--project-id <hex>", "projectId (required when scope=project)").action(async (opts) => {
     const categoryR = parseEnum(opts.category, SkillCategorySchema, "category");
     if (!categoryR.success) {
       renderResult("json", categoryR);
@@ -3661,6 +3963,11 @@ function createSkillCommand() {
       renderResult("json", scopeR);
       return;
     }
+    const refsR = parseRefFlags(opts.ref ?? [], SKILL_MAIN_DOC4);
+    if (!refsR.success) {
+      renderResult("json", refsR);
+      return;
+    }
     const client = createClient(opts.url);
     const input = {
       name: opts.name,
@@ -3669,12 +3976,13 @@ function createSkillCommand() {
       category: categoryR.data,
       scope: scopeR.data,
       version: "1.0.0",
+      ...refsR.data.length > 0 ? { references: refsR.data } : {},
       ...opts.projectId ? { projectId: opts.projectId } : {}
     };
     const result = await handleCreateSkill(client, input);
     renderResult("json", result);
   });
-  skill.command("update <name>").description("Update a skill (partial)").option("--url <url>", "server base URL").option("--description <text>", "new description").option("--content <text>", "new content").option("--version <v>", "new version").option("--scope <scope>", "global|project").option("--project-id <hex>", "projectId").action(async (name, opts) => {
+  skill.command("update <name>").description("Update a skill (partial; references untouched unless --ref/--clear-refs given)").option("--url <url>", "server base URL").option("--description <text>", "new description").option("--content <text>", "new content").option("--version <v>", "new version").option("--scope <scope>", "global|project").option("--ref <path@file>", "replace all reference docs: <relative path>@<local file> (repeatable)", collectArgs, []).option("--clear-refs", "remove all reference docs (mutually exclusive with --ref)").option("--project-id <hex>", "projectId").action(async (name, opts) => {
     const client = createClient(opts.url);
     let scope;
     if (opts.scope !== void 0) {
@@ -3685,11 +3993,31 @@ function createSkillCommand() {
       }
       scope = scopeR.data;
     }
+    let references;
+    if (opts.clearRefs === true && (opts.ref ?? []).length > 0) {
+      renderResult("json", fail({
+        message: "--clear-refs \u4E0E --ref \u4E92\u65A5\uFF0C\u4E8C\u9009\u4E00",
+        httpStatus: 0,
+        hint: "\u6E05\u7A7A\u5F15\u7528\u7528 --clear-refs\uFF1B\u66FF\u6362\u5F15\u7528\u7528 --ref path@file\uFF08\u53EF\u91CD\u590D\uFF09"
+      }));
+      return;
+    }
+    if (opts.clearRefs === true) {
+      references = [];
+    } else if ((opts.ref ?? []).length > 0) {
+      const refsR = parseRefFlags(opts.ref ?? [], SKILL_MAIN_DOC4);
+      if (!refsR.success) {
+        renderResult("json", refsR);
+        return;
+      }
+      references = refsR.data;
+    }
     const patch = {
       ...opts.description !== void 0 ? { description: opts.description } : {},
       ...opts.content !== void 0 ? { content: opts.content } : {},
       ...opts.version !== void 0 ? { version: opts.version } : {},
       ...scope !== void 0 ? { scope } : {},
+      ...references !== void 0 ? { references } : {},
       ...opts.projectId !== void 0 ? { projectId: opts.projectId } : {}
     };
     const result = await handleUpdateSkill(client, name, patch);
@@ -3724,13 +4052,15 @@ function skillFields(s) {
     ["projectId", s.projectId],
     ["version", s.version],
     ["description", s.description],
-    ["content", s.content.length > 200 ? s.content.slice(0, 200) + "\u2026" : s.content]
+    ["content", s.content.length > 200 ? s.content.slice(0, 200) + "\u2026" : s.content],
+    // T202608270002：引用文档清单（path 列表；无引用时不显示该行）
+    ...s.references?.length ? [["references", s.references.map((r) => r.path).join(", ")]] : []
   ];
 }
 
 // src/commands/agent/command.ts
 import { Command as Command7 } from "commander";
-import { AgentScopeSchema as AgentScopeSchema2 } from "@siming-org/core";
+import { AGENT_MAIN_DOC as AGENT_MAIN_DOC4, AgentScopeSchema as AgentScopeSchema2, AgentFunctionSchema as AgentFunctionSchema2 } from "@siming-org/core";
 function createAgentCommand() {
   const agent = new Command7("agent").description("Agent management \u2014 subagent definitions (global/project scope)");
   withCommonOpts(agent.command("list"), "table").option("--project <id>", "filter by projectId").description("List agents").action(async (opts) => {
@@ -3741,7 +4071,9 @@ function createAgentCommand() {
         { key: "name", header: "Name" },
         { key: "model", header: "Model" },
         { key: "scope", header: "Scope" },
+        { key: "function", header: "Function" },
         { key: "boundSkills", header: "Bound Skills", maxWidth: 30 },
+        { key: "referenceCount", header: "Refs" },
         { key: "description", header: "Description", maxWidth: 40 }
       ]
     });
@@ -3751,12 +4083,26 @@ function createAgentCommand() {
     const result = await handleGetAgent(client, name);
     renderResult(opts.format, result, { fields: result.success ? agentFields(result.data) : [] });
   });
-  agent.command("create").description("Create an agent (scope + system-prompt + model required)").option("--url <url>", "server base URL").requiredOption("--name <name>", "agent name").requiredOption("--description <text>", "agent description").requiredOption("--system-prompt <text>", "system prompt").requiredOption("--model <code>", "model siming-code (kebab-case)").requiredOption("--scope <scope>", "global|project").option("--bound-skill <name>", "bound skill name (repeatable)", collectArgs, []).option("--tool <name>", "tool name (repeatable)", collectArgs, []).option("--permission <name>", "permission name (repeatable)", collectArgs, []).option("--project-id <hex>", "projectId (required when scope=project)").action(async (opts) => {
+  agent.command("create").description("Create an agent (scope + system-prompt + model required)").option("--url <url>", "server base URL").requiredOption("--name <name>", "agent name").requiredOption("--description <text>", "agent description").requiredOption("--system-prompt <text>", "system prompt").requiredOption("--model <code>", "model siming-code (kebab-case)").requiredOption("--scope <scope>", "global|project").option("--function <function>", "agent function: reviewer|executor (default executor)").option("--bound-skill <name>", "bound skill name (repeatable)", collectArgs, []).option("--tool <name>", "tool name (repeatable)", collectArgs, []).option("--permission <name>", "permission name (repeatable)", collectArgs, []).option("--ref <path@file>", "reference doc: <relative path>@<local file> (repeatable)", collectArgs, []).option("--project-id <hex>", "projectId (required when scope=project)").action(async (opts) => {
     const scopeR = parseEnum(opts.scope, AgentScopeSchema2, "scope");
     if (!scopeR.success) {
       renderResult("json", scopeR);
       return;
     }
+    let agentFunction;
+    if (opts.function !== void 0) {
+      const fnR = parseEnum(opts.function, AgentFunctionSchema2, "function");
+      if (!fnR.success) {
+        renderResult("json", fnR);
+        return;
+      }
+      agentFunction = fnR.data;
+    }
+    const refsR = parseRefFlags(opts.ref ?? [], AGENT_MAIN_DOC4);
+    if (!refsR.success) {
+      renderResult("json", refsR);
+      return;
+    }
     const client = createClient(opts.url);
     const input = {
       name: opts.name,
@@ -3765,15 +4111,18 @@ function createAgentCommand() {
       model: opts.model,
       version: "1.0.0",
       scope: scopeR.data,
+      // AgentCreate 输出类型 function 必有：显式缺省 executor（与 API 缺省归一一致）
+      "function": agentFunction ?? "executor",
       boundSkills: opts.boundSkill,
       tools: opts.tool,
       permissions: opts.permission,
+      ...refsR.data.length > 0 ? { references: refsR.data } : {},
       ...opts.projectId ? { projectId: opts.projectId } : {}
     };
     const result = await handleCreateAgent(client, input);
     renderResult("json", result);
   });
-  agent.command("update <name>").description("Update an agent (partial)").option("--url <url>", "server base URL").option("--description <text>", "new description").option("--system-prompt <text>", "new system prompt").option("--model <code>", "new model siming-code").option("--scope <scope>", "global|project").option("--bound-skill <name>", "replace bound skills (repeatable)", collectArgs, []).option("--tool <name>", "replace tools (repeatable)", collectArgs, []).option("--permission <name>", "replace permissions (repeatable)", collectArgs, []).option("--project-id <hex>", "projectId").action(async (name, opts) => {
+  agent.command("update <name>").description("Update an agent (partial)").option("--url <url>", "server base URL").option("--description <text>", "new description").option("--system-prompt <text>", "new system prompt").option("--model <code>", "new model siming-code").option("--scope <scope>", "global|project").option("--function <function>", "new agent function: reviewer|executor").option("--bound-skill <name>", "replace bound skills (repeatable)", collectArgs, []).option("--tool <name>", "replace tools (repeatable)", collectArgs, []).option("--permission <name>", "replace permissions (repeatable)", collectArgs, []).option("--ref <path@file>", "replace all reference docs: <relative path>@<local file> (repeatable)", collectArgs, []).option("--clear-refs", "remove all reference docs (mutually exclusive with --ref)").option("--project-id <hex>", "projectId").action(async (name, opts) => {
     const client = createClient(opts.url);
     let scope;
     if (opts.scope !== void 0) {
@@ -3784,14 +4133,44 @@ function createAgentCommand() {
       }
       scope = scopeR.data;
     }
+    let agentFunction;
+    if (opts.function !== void 0) {
+      const fnR = parseEnum(opts.function, AgentFunctionSchema2, "function");
+      if (!fnR.success) {
+        renderResult("json", fnR);
+        return;
+      }
+      agentFunction = fnR.data;
+    }
+    let references;
+    if (opts.clearRefs === true && opts.ref.length > 0) {
+      renderResult("json", fail({
+        message: "--clear-refs \u4E0E --ref \u4E92\u65A5\uFF0C\u4E8C\u9009\u4E00",
+        httpStatus: 0,
+        hint: "\u6E05\u7A7A\u5F15\u7528\u7528 --clear-refs\uFF1B\u66FF\u6362\u5F15\u7528\u7528 --ref path@file\uFF08\u53EF\u91CD\u590D\uFF09"
+      }));
+      return;
+    }
+    if (opts.clearRefs === true) {
+      references = [];
+    } else if (opts.ref.length > 0) {
+      const refsR = parseRefFlags(opts.ref, AGENT_MAIN_DOC4);
+      if (!refsR.success) {
+        renderResult("json", refsR);
+        return;
+      }
+      references = refsR.data;
+    }
     const patch = {
       ...opts.description !== void 0 ? { description: opts.description } : {},
       ...opts.systemPrompt !== void 0 ? { systemPrompt: opts.systemPrompt } : {},
       ...opts.model !== void 0 ? { model: opts.model } : {},
       ...scope !== void 0 ? { scope } : {},
+      ...agentFunction !== void 0 ? { "function": agentFunction } : {},
       ...opts.boundSkill.length > 0 ? { boundSkills: opts.boundSkill } : {},
       ...opts.tool.length > 0 ? { tools: opts.tool } : {},
       ...opts.permission.length > 0 ? { permissions: opts.permission } : {},
+      ...references !== void 0 ? { references } : {},
       ...opts.projectId !== void 0 ? { projectId: opts.projectId } : {}
     };
     const result = await handleUpdateAgent(client, name, patch);
@@ -3823,16 +4202,20 @@ function agentFields(a) {
     ["name", a.name],
     ["model", a.model],
     ["scope", a.scope],
+    ["function", a["function"]],
     ["projectId", a.projectId],
     ["boundSkills", a.boundSkills],
     ["tools", a.tools],
     ["permissions", a.permissions],
+    // T202608270002：引用文档清单（path 列表；无引用时不显示该行）
+    ...a.references?.length ? [["references", a.references.map((r) => r.path).join(", ")]] : [],
     ["description", a.description],
     ["systemPrompt", a.systemPrompt]
   ];
 }
 
 // src/commands/dag/command.ts
+import { readFileSync as readFileSync9 } from "fs";
 import { Command as Command8 } from "commander";
 function createDagCommand() {
   const dag = new Command8("dag").description("DAG template & instance management");
@@ -3866,13 +4249,26 @@ function createDagCommand() {
     const result = await handleGetTemplate(client, templateId);
     renderResult(opts.format, result, { fields: result.success ? templateFields(result.data) : [] });
   });
-  tpl.command("import <file>").description("Import template from YAML (DagTemplateCreateSchema \u7684 YAML \u8868\u793A)").option("--url <url>", "server base URL").option("--project <id>", "override projectId (defaults to YAML projectId)").option("--name <name>", "override template name").action(async (file, opts) => {
+  tpl.command("import <file>").description(
+    "Import a DAG template from file \u2014 bundle JSON (with dependency closure, plan\u2192apply) or YAML single template (format auto-detected by content)"
+  ).option("--url <url>", "server base URL").option("--project <key|id>", "target project (key or id); YAML channel: overrides projectId, bundle channel: import target").option("--name <name>", "override template name (YAML channel only)").option("--overwrite-deps", "bundle channel: force-overwrite conflicting dependencies").option("--plan", "bundle channel: preview only (plan without apply)").action(async (file, opts) => {
     const client = createClient(opts.url);
-    const result = await handleImportTemplate(client, file, {
-      ...opts.project ? { projectId: opts.project } : {},
-      ...opts.name ? { name: opts.name } : {}
-    });
-    renderResult("json", result);
+    let text;
+    try {
+      text = readFileSync9(file, "utf-8");
+    } catch (e) {
+      renderResult("json", fail({
+        message: `\u6587\u4EF6\u8BFB\u53D6\u5931\u8D25: ${file}\uFF08${e instanceof Error ? e.message : String(e)}\uFF09`,
+        httpStatus: 0,
+        hint: "\u786E\u8BA4\u8DEF\u5F84\u5B58\u5728\u4E14\u53EF\u8BFB\uFF1Bnpm \u5168\u5C40\u5B89\u88C5\u7684\u5185\u7F6E\u6A21\u677F\u4F4D\u4E8E <\u5B89\u88C5\u76EE\u5F55>/node_modules/@siming-org/cli/templates/builtin/"
+      }));
+      return;
+    }
+    if (isBundleText(text)) {
+      await runBundleImport(client, text, opts);
+      return;
+    }
+    await runYamlImport(client, text, opts, jsonParseError(text));
   });
   const inst = dag.command("instance").description("Task DAG instance");
   withCommonOpts(inst.command("show <taskId>"), "fancy").description("Show task DAG instance").action(async (taskId, opts) => {
@@ -3919,6 +4315,146 @@ function pausePointsText(row) {
   if (!Array.isArray(pp) || pp.length === 0) return "\u2014";
   return pp.join(", ");
 }
+function isBundleText(text) {
+  try {
+    const parsed = JSON.parse(text);
+    return typeof parsed === "object" && parsed !== null && "exportFormatVersion" in parsed;
+  } catch {
+    return false;
+  }
+}
+function jsonParseError(text) {
+  try {
+    JSON.parse(text);
+    return void 0;
+  } catch (e) {
+    return e instanceof Error ? e.message : String(e);
+  }
+}
+async function runYamlImport(client, yamlText, opts, jsonParseError2) {
+  if (opts.plan === true || opts.overwriteDeps === true) {
+    renderResult("json", fail({
+      message: "--plan / --overwrite-deps \u4EC5\u5BF9 bundle \u6587\u4EF6\u751F\u6548\uFF08\u5F53\u524D\u6587\u4EF6\u8BC6\u522B\u4E3A YAML \u5355\u6A21\u677F\uFF09",
+      httpStatus: 0,
+      hint: "bundle \u662F export \u7AEF\u70B9\u4EA7\u7269\uFF08JSON \u542B exportFormatVersion \u4E0E\u4F9D\u8D56\u95ED\u5305\uFF09\uFF1BYAML \u5355\u6A21\u677F\u5BFC\u5165\u65E0\u51B2\u7A81\u51B3\u7B56\u73AF\u8282"
+    }));
+    return;
+  }
+  let projectId;
+  if (opts.project !== void 0) {
+    const r = await resolveProjectId(client, opts.project);
+    if (!r.success) {
+      renderResult("json", r);
+      return;
+    }
+    projectId = r.data;
+  }
+  const result = await importTemplateFromYaml(client, yamlText, {
+    ...projectId !== void 0 ? { projectId } : {},
+    ...opts.name !== void 0 ? { name: opts.name } : {}
+  });
+  if (!result.success && jsonParseError2 !== void 0 && result.error.bizCode === "YAML_PARSE_FAILED") {
+    renderResult("json", fail({
+      message: `\u6587\u4EF6\u65E2\u975E bundle \u4E5F\u975E\u6A21\u677F YAML\uFF1A
+JSON \u89E3\u6790: ${jsonParseError2}
+YAML \u89E3\u6790: ${result.error.message}`,
+      httpStatus: 0,
+      hint: "bundle \u662F export \u7AEF\u70B9\u4EA7\u7269\uFF08JSON \u9876\u5C42\u542B exportFormatVersion\uFF09\uFF1B\u6A21\u677F YAML \u987B\u7B26\u5408 DagTemplateCreateSchema\uFF08\u89C1 CLI \u4F7F\u7528\u624B\u518C \xA714\uFF09"
+    }));
+    return;
+  }
+  renderResult("json", result);
+}
+async function runBundleImport(client, bundleText, opts) {
+  if (opts.name !== void 0) {
+    renderResult("json", fail({
+      message: "--name \u4EC5\u5BF9 YAML \u6A21\u677F\u751F\u6548\uFF08bundle \u6A21\u677F\u540D\u4EE5\u5BFC\u51FA\u5FEB\u7167\u4E3A\u51C6\uFF0C\u547D\u4EE4\u5C42\u4E0D\u91CD\u547D\u540D\uFF09",
+      httpStatus: 0,
+      hint: "\u5BFC\u5165\u540E\u53EF\u5728 Web \u7BA1\u7406\u53F0\u7F16\u8F91\u6A21\u677F\u4FE1\u606F\uFF1B\u81EA\u5B9A\u4E49\u540D\u8BF7\u8D70 YAML \u901A\u9053"
+    }));
+    return;
+  }
+  const target = await resolveImportTargetProject(client, opts.project);
+  if (!target.success) {
+    renderResult("json", target);
+    return;
+  }
+  const result = await importTemplateBundle(client, bundleText, {
+    targetProjectId: target.data,
+    ...opts.overwriteDeps === true ? { overwriteDeps: true } : {},
+    ...opts.plan === true ? { planOnly: true } : {}
+  });
+  if (!result.success) {
+    renderResult("json", result);
+    return;
+  }
+  renderBundleImportOutcome(result.data, opts.plan === true);
+}
+async function resolveImportTargetProject(client, projectOpt) {
+  if (projectOpt !== void 0) return resolveProjectId(client, projectOpt);
+  const wsDefault = readWorkspaceConfig()?.defaultProject;
+  if (wsDefault !== void 0) {
+    const r = await resolveProjectId(client, wsDefault);
+    if (!r.success) {
+      return fail({
+        ...r.error,
+        hint: `workspace defaultProject "${wsDefault}" \u89E3\u6790\u5931\u8D25\u2014\u2014siming config unset defaultProject \u540E\u91CD\u8BD5\uFF0C\u6216\u663E\u5F0F --project <key|id>`
+      });
+    }
+    return r;
+  }
+  const list = await handleListProjects(client);
+  if (!list.success) return list;
+  const defaultProject = list.data.find((p) => p.key === "default");
+  if (defaultProject?.id === void 0) {
+    return fail({
+      message: "bundle \u5BFC\u5165\u9700\u8981\u76EE\u6807\u9879\u76EE\uFF1A\u672A\u6307\u5B9A --project\uFF0C\u5DE5\u4F5C\u533A\u65E0 defaultProject\uFF0C\u5B9E\u4F8B\u4E2D\u4E5F\u65E0 key=default \u7684\u9879\u76EE",
+      httpStatus: 0,
+      hint: "pass --project <key|id>\uFF0C\u6216\u5148 siming project create + siming init --project <key>"
+    });
+  }
+  return { success: true, data: defaultProject.id };
+}
+function renderBundleImportOutcome(outcome, planOnly) {
+  const t = outcome.plan.template;
+  const overwritten = t.willOverwrite && t.currentVersion !== void 0 ? `\u8986\u76D6\u73B0\u6709 v${t.currentVersion} \u2192 ` : "";
+  console.log(`\u6A21\u677F ${t.name}: ${overwritten}v${t.importVersion}`);
+  if (!t.isDefaultEffect) {
+    console.log(`  \u9ED8\u8BA4\u6A21\u677F: \u751F\u6548 false${t.downgradeReason !== void 0 ? `\uFF08${t.downgradeReason}\uFF09` : ""}`);
+  }
+  const byStatus = countBy(outcome.plan.dependencies, (d) => d.status);
+  console.log(
+    `\u4F9D\u8D56\u9884\u68C0: create ${byStatus.create ?? 0} / identical ${byStatus.identical ?? 0} / conflict ${byStatus.conflict ?? 0}`
+  );
+  for (const d of outcome.plan.dependencies) {
+    if (d.status !== "conflict") continue;
+    const scope = d.scope !== void 0 ? `(${d.scope})` : "";
+    const versions = d.currentVersion !== void 0 ? ` v${d.currentVersion} \u2192 v${d.importVersion ?? "?"}` : "";
+    const diff = d.changeSummary !== void 0 ? ` \u5DEE\u5F02: ${d.changeSummary}` : "";
+    console.log(`  conflict [${d.kind}] ${d.name}${scope}${versions}${diff}`);
+  }
+  for (const w of outcome.plan.warnings) console.log(`  \u8B66\u544A: ${w}`);
+  if (outcome.apply === void 0) {
+    console.log(planOnly ? "\u2500\u2500 \u4EC5\u9884\u68C0\uFF08--plan\uFF09\uFF0C\u672A\u6267\u884C\u5BFC\u5165 \u2500\u2500" : "\u2500\u2500 \u672A\u6267\u884C\u5BFC\u5165 \u2500\u2500");
+    return;
+  }
+  const byAction = countBy(outcome.apply.dependencies, (d) => d.action);
+  console.log(
+    `\u5BFC\u5165\u5B8C\u6210: \u6A21\u677F ${outcome.apply.template.action}\uFF08id ${outcome.apply.template.id}\uFF09\uFF1B\u4F9D\u8D56 created ${byAction.created ?? 0} / updated ${byAction.updated ?? 0} / skipped ${byAction.skipped ?? 0} / identical ${byAction.identical ?? 0} / failed ${byAction.failed ?? 0}`
+  );
+  for (const d of outcome.apply.dependencies) {
+    if (d.action !== "failed") continue;
+    console.log(`  failed [${d.kind}] ${d.name}${d.message !== void 0 ? `: ${d.message}` : ""}`);
+  }
+}
+function countBy(items, keyOf) {
+  const counts = {};
+  for (const item of items) {
+    const k = keyOf(item);
+    counts[k] = (counts[k] ?? 0) + 1;
+  }
+  return counts;
+}
 
 // src/commands/sync/command.ts
 import { Command as Command9 } from "commander";
@@ -4061,7 +4597,7 @@ function createConfigCommand() {
 
 // src/commands/export/command.ts
 import { Command as Command12 } from "commander";
-import { readFileSync as readFileSync8 } from "fs";
+import { readFileSync as readFileSync10 } from "fs";
 import { parse as parseYaml3 } from "yaml";
 function createExportCommand() {
   const exportCmd = new Command12("export").description("Export local assets (skills/agents/dags) to Siming \u2014 plan then apply");
@@ -4106,7 +4642,7 @@ function createExportCommand() {
 async function runExportPlan(client, filePath, typesArg) {
   let raw;
   try {
-    const text = readFileSync8(filePath, "utf-8");
+    const text = readFileSync10(filePath, "utf-8");
     raw = parseYaml3(text);
   } catch (e) {
     return fail({
@@ -4131,7 +4667,7 @@ async function runExportPlan(client, filePath, typesArg) {
 }
 function loadPlanFile(path) {
   try {
-    const text = readFileSync8(path, "utf-8");
+    const text = readFileSync10(path, "utf-8");
     const parsed = JSON.parse(text);
     if (!Array.isArray(parsed.items)) {
       return fail({ message: `\u8BA1\u5212\u6587\u4EF6\u7ED3\u6784\u65E0\u6548\uFF1A\u7F3A\u5C11 items \u6570\u7EC4`, httpStatus: 0, hint: "\u8BA1\u5212\u6587\u4EF6\u7531 `siming export plan --format json > plan.json` \u751F\u6210" });
@@ -4192,11 +4728,121 @@ function renderReport(report, format) {
   }
 }
 
-// src/commands/settings/command.ts
+// src/commands/guide.ts
 import { Command as Command13 } from "commander";
+
+// src/commands/guide-content.ts
+var GUIDE_TEXT = `================================================================
+\u65B0\u9879\u76EE\u63A5\u5165 siming \u5F00\u53D1\u6D41\u7A0B\u6307\u5BFC
+================================================================
+
+\u672C\u6307\u5BFC\u9762\u5411\u9996\u6B21\u5C06\u9879\u76EE\u63A5\u5165 siming \u5F00\u53D1\u6D41\u7A0B\u7684\u6280\u672F\u8D1F\u8D23\u4EBA\u4E0E AI \u7F16\u7A0B\u4EE3\u7406\uFF0C
+\u8986\u76D6\u56DB\u6B65\uFF1A\u8865\u9F50\u9879\u76EE\u58F0\u660E \u2192 \u914D\u7F6E\u6D41\u7A0B\u6A21\u677F \u2192 \u5EFA\u7ACB\u9879\u76EE\u7EA7\u8D44\u4EA7 \u2192 \u9A8C\u8BC1\u63A5\u5165\u3002
+
+----------------------------------------------------------------
+\u4E00\u3001\u9879\u76EE AGENTS.md \u5FC5\u5907\u58F0\u660E checklist
+----------------------------------------------------------------
+
+\u6D41\u7A0B\u6A21\u677F\u7684\u8282\u70B9\u63D0\u793A\u8BCD\u4E2D\uFF0C\u73AF\u5883\u76F8\u5173\u4FE1\u606F\u5168\u90E8\u53C2\u6570\u5316\u4E3A\u300C\u6309\u9879\u76EE\u58F0\u660E\u300D\uFF0C
+\u58F0\u660E\u503C\u843D\u70B9 = \u9879\u76EE\u4ED3\u5E93\u7684 AI \u5165\u53E3\u6587\u4EF6\uFF08\u9879\u76EE AGENTS.md\uFF09\u3002
+\u4EE5\u4E0B 8 \u9879\u58F0\u660E\u4E0D\u9F50\u65F6\uFF0C\u6D41\u7A0B\u4F1A\u5728\u5BF9\u5E94\u73AF\u8282\u6682\u505C\u8BE2\u95EE\u6216\u964D\u7EA7\uFF1A
+
+| # | \u58F0\u660E\u9879 | \u58F0\u660E\u5185\u5BB9 | \u7F3A\u5931\u540E\u679C |
+|---|--------|----------|----------|
+| 1 | \u5206\u652F\u6A21\u578B | \u4E3B\u7EBF/\u5F00\u53D1/\u4EFB\u52A1\u5206\u652F\u7684\u547D\u540D\u4E0E\u521B\u5EFA\u89C4\u5219 | \u5206\u652F\u5BF9\u9F50\u73AF\u8282\u65E0\u6CD5\u786E\u5B9A\u4E3B\u7EBF\u5206\u652F\u540D\uFF0C\u6682\u505C\u8BE2\u95EE |
+| 2 | COMMANDS | \u5B89\u88C5/\u6784\u5EFA/\u7C7B\u578B\u68C0\u67E5/\u6D4B\u8BD5\u7684\u53EF\u6267\u884C\u547D\u4EE4 | \u7F16\u7801\u4E0E\u6D4B\u8BD5\u73AF\u8282\u65E0\u6CD5\u786E\u5B9A\u6267\u884C\u547D\u4EE4\uFF0C\u6682\u505C\u8BE2\u95EE |
+| 3 | \u6D4B\u8BD5\u8303\u5F0F | \u6D4B\u8BD5\u6846\u67B6\u3001\u547D\u540D\u7EA6\u5B9A\u3001PASS \u5224\u5B9A\u6807\u51C6 | \u5355\u6D4B/E2E \u8BBE\u8BA1\u4E0E\u5F00\u53D1\u73AF\u8282\u7F3A\u5C11\u4F9D\u636E\uFF0C\u6682\u505C\u8BE2\u95EE |
+| 4 | \u6D41\u7A0B\u6587\u6863\u76EE\u5F55 | PRD/\u6280\u672F\u65B9\u6848/\u6D4B\u8BD5\u8BBE\u8BA1\u7B49\u6D41\u7A0B\u4EA7\u7269\u843D\u76D8\u4F4D\u7F6E | \u6587\u6863\u7C7B\u8282\u70B9\u4EA7\u7269\u65E0\u843D\u70B9\uFF0C\u6682\u505C\u8BE2\u95EE |
+| 5 | \u67B6\u6784\u6587\u6863\u76EE\u5F55 | \u4E1A\u52A1/\u6280\u672F/E2E/UI \u67B6\u6784\u51B3\u7B56\u6587\u6863\u4F4D\u7F6E | \u8BBE\u8BA1\u73AF\u8282\u7F3A\u5C11\u65E2\u6709\u67B6\u6784\u51B3\u7B56\u8F93\u5165\uFF08\u53EF\u964D\u7EA7\u8DF3\u8FC7\u4F46\u635F\u5931\u5BF9\u9F50\uFF09 |
+| 6 | E2E \u552F\u4E00\u6267\u884C\u5165\u53E3 | E2E \u6D4B\u8BD5\u552F\u4E00\u5408\u6CD5\u7684\u6267\u884C\u547D\u4EE4/\u811A\u672C | E2E \u5F00\u53D1\u73AF\u8282\u65E0\u6CD5\u786E\u5B9A\u6267\u884C\u65B9\u5F0F\uFF0C\u6682\u505C\u8BE2\u95EE |
+| 7 | \u6D4B\u8BD5\u5B8C\u6574\u6027\u68C0\u67E5 | \u9632\u5220\u6D4B/\u7981 skip \u7684\u9759\u6001\u68C0\u67E5\u547D\u4EE4 | \u6D4B\u8BD5\u6536\u5C3E\u7F3A\u5C11\u95E8\u7981\u4F9D\u636E\uFF0C\u6682\u505C\u8BE2\u95EE |
+| 8 | \u547D\u4EE4\u65E5\u5FD7\u843D\u76D8 | \u6784\u5EFA/\u6D4B\u8BD5\u547D\u4EE4\u7684\u65E5\u5FD7\u5F52\u6863\u7EA6\u5B9A | \u547D\u4EE4\u6267\u884C\u65E0\u6CD5\u56DE\u6EAF\uFF0C\u5F52\u6863\u8282\u70B9\u8BC1\u636E\u4E0D\u8DB3 |
+
+----------------------------------------------------------------
+\u4E8C\u3001\u6D41\u7A0B\u6A21\u677F\u83B7\u53D6\u6307\u5F15
+----------------------------------------------------------------
+
+\u65B0\u9879\u76EE\u9700\u8981\u81EA\u5DF1\u7684 DAG \u6D41\u7A0B\u6A21\u677F\uFF08\u6D41\u7A0B\u7ED3\u6784\u4EE5\u9879\u76EE\u5B9E\u4F8B\u5185\u6A21\u677F\u4E3A\u6743\u5A01\uFF09\uFF0C
+\u4E09\u6761\u83B7\u53D6\u8DEF\u5F84\uFF0C\u8DEF\u5F84 0 \u4E3A\u5168\u65B0\u5B9E\u4F8B\u7684\u63A8\u8350\u8D77\u70B9\uFF1A
+
+0. npm \u5305\u5185\u7F6E\u57FA\u7840\u6A21\u677F\uFF1A@siming-org/cli \u5305\u5185\u81EA\u5E26 3 \u4E2A\u7ECF\u8FC7\u9A8C\u8BC1\u7684\u5B8C\u6574
+   \u5DE5\u4F5C\u6D41 bundle\uFF08\u542B\u4F9D\u8D56\u95ED\u5305 skills/agents/\u6A21\u578B\u522B\u540D\uFF0C\u5BFC\u5165\u5373\u5B8C\u6574\u53EF\u7528\uFF09\uFF1A
+   - full_workflow      \u5B8C\u6574\u529F\u80FD\u5F00\u53D1\u6D41\u7A0B\uFF08feature \u7C7B\u4EFB\u52A1\u5168\u6D41\u7A0B\uFF09
+   - research_workflow  \u8C03\u7814\u4EFB\u52A1\u6D41\u7A0B\uFF08\u4EA7\u51FA\u8C03\u7814\u62A5\u544A\uFF09
+   - quick_fix_workflow \u5FEB\u901F\u4FEE\u590D\u6D41\u7A0B\uFF08bugfix \u7C7B\u4EFB\u52A1\uFF09
+   \u6587\u4EF6\u5B9A\u4F4D\uFF1Anpm \u5168\u5C40\u5B89\u88C5\u5728 <\u5168\u5C40 node_modules>/@siming-org/cli/templates/builtin/\uFF1B
+   tarball \u901A\u9053\u5B89\u88C5\u5728 <\u5B89\u88C5\u76EE\u5F55>/node_modules/@siming-org/cli/templates/builtin/
+   \uFF08\u5982 ~/siming-prod\uFF09\u3002\u6587\u4EF6\u540D\u5F62\u5982 full_workflow.bundle.json\u3002
+   \u5B89\u88C5\uFF08\u4E8C\u9009\u4E00\uFF09\uFF1A
+   - CLI \u547D\u4EE4\uFF1Asiming dag template import <bundle \u6587\u4EF6\u8DEF\u5F84>
+     \uFF08\u6309\u5185\u5BB9\u81EA\u52A8\u8BC6\u522B bundle \u683C\u5F0F\uFF0C\u9884\u68C0+\u6267\u884C\u53CC\u9636\u6BB5\uFF1B--project <key|id> \u6307\u5B9A
+     \u76EE\u6807\u9879\u76EE\uFF0C\u7F3A\u7701\u7528\u5DE5\u4F5C\u533A defaultProject\uFF1B--plan \u53EA\u9884\u68C0\u4E0D\u6267\u884C\uFF1B
+     --overwrite-deps \u51B2\u7A81\u4F9D\u8D56\u5F3A\u5236\u8986\u76D6\uFF09
+   - Web \u7BA1\u7406\u53F0\uFF1ADAG \u6A21\u677F\u9875\u5BFC\u5165\u5411\u5BFC\u4E0A\u4F20\u540C\u4E00 bundle \u6587\u4EF6
+   \u901A\u9053\u8FB9\u754C\uFF1AMCP siming_template import \u4EC5\u652F\u6301\u5355\u6A21\u677F YAML\uFF08\u4E0D\u5E26\u4F9D\u8D56\u95ED\u5305\uFF09\uFF0C
+   \u5B8C\u6574\u5B89\u88C5\u8D70 CLI \u547D\u4EE4\u6216 Web \u5411\u5BFC\u3002
+   \u5BFC\u5165\u540E\u5373\u4E3A\u666E\u901A\u8D44\u4EA7\uFF1A\u53EF\u7F16\u8F91/\u590D\u5236\u5B9A\u5236\uFF1B\u6A21\u578B\u522B\u540D\u5EFA\u8BAE\u6309\u672C\u9879\u76EE\u6A21\u578B\u914D\u7F6E\u4FEE\u6539\u3002
+
+1. \u5B9E\u4F8B\u5185\u590D\u5236\uFF1A\u82E5\u672C siming \u5B9E\u4F8B\u5DF2\u6709\u7ED3\u6784\u53EF\u53C2\u8003\u7684\u9879\u76EE\u6A21\u677F\uFF0C
+   \u5728 Web \u7BA1\u7406\u53F0 DAG \u6A21\u677F\u9875\u4F7F\u7528\u590D\u5236\u529F\u80FD\uFF08\u6E90\u6A21\u677F\u4E0D\u52A8\uFF0C\u526F\u672C\u53EF\u7F16\u8F91\uFF09\u3002
+
+2. \u8DE8\u5B9E\u4F8B\u8FC1\u79FB\uFF1A\u4ECE\u6E90\u5B9E\u4F8B\u53D6\u6A21\u677F\u5B8C\u6574\u7ED3\u6784\uFF08siming dag template show
+   <\u6A21\u677F> --format json\uFF0C\u542B\u8282\u70B9/\u8FDE\u7EBF/\u63D0\u793A\u8BCD\u5168\u91CF\uFF09\uFF0C\u6574\u7406\u4E3A YAML \u540E\u5728\u76EE\u6807
+   \u5B9E\u4F8B\u6267\u884C siming dag template import <file.yaml> \u5BFC\u5165\uFF1B\u6216\u6574\u7406\u4E3A
+   export \u6761\u76EE\u6587\u4EF6\uFF08dags \u6570\u7EC4\uFF09\u7ECF siming export apply \u4E0A\u4F20\u3002
+
+   AI \u7F16\u7A0B\u4EE3\u7406\u53EF\u7ECF MCP \u5DE5\u5177\u64CD\u4F5C\uFF1Asiming_template\uFF08list/show/import\uFF09\u3002
+
+----------------------------------------------------------------
+\u4E09\u3001\u9879\u76EE\u7EA7\u8D44\u4EA7\u6307\u8DEF
+----------------------------------------------------------------
+
+\u4EE5\u4E0B\u4E24\u7C7B\u9879\u76EE\u4F5C\u7528\u57DF skill \u8D44\u4EA7\u5EFA\u8BAE\u6BCF\u4E2A\u63A5\u5165\u9879\u76EE\u81EA\u5EFA\u4E00\u4EFD
+\uFF08\u6B64\u5904\u53EA\u6307\u8DEF\u4E0D\u590D\u5236\u5185\u5BB9\uFF0C\u7248\u672C\u4EE5\u9879\u76EE\u5B9E\u4F8B\u5185\u5B9E\u9645\u4E3A\u51C6\uFF09\uFF1A
+
+1. task-create \u2014\u2014 \u4EFB\u52A1\u521B\u5EFA\u5165\u53E3\u6307\u5F15\uFF1A\u672C\u9879\u76EE\u300C\u4EFB\u52A1\u7C7B\u578B \xD7 \u8F68\u9053 \u2192 \u6A21\u677F\u4E0E
+   \u526A\u679D\u300D\u5339\u914D\u89C4\u5219\u7684\u5B9A\u5236\u7248\uFF08\u542B\u4FEE\u8BA2\u6E05\u5355\uFF09\u3002\u83B7\u53D6\u65B9\u5F0F\uFF1A\u4ECE\u65E2\u6709\u9879\u76EE\u590D\u5236\u540E
+   \u6309\u672C\u9879\u76EE\u6A21\u677F\u5217\u8868\u4FEE\u8BA2\uFF0C\u6216\u6309\u540C\u540D\u8D44\u4EA7\u7ED3\u6784\u65B0\u5EFA\u3002
+
+2. siming-arch \u2014\u2014 \u67B6\u6784\u6587\u6863\u7D22\u5F15\uFF1A\u6307\u5411\u672C\u9879\u76EE\u4ED3\u5E93\u67B6\u6784\u6587\u6863\u76EE\u5F55\u7684\u9AA8\u67B6
+   \uFF08\u6BCF\u9879\u76EE\u4E00\u4EFD\uFF1B\u67B6\u6784\u6587\u6863\u5B9E\u4F53\u5B58\u9879\u76EE\u4ED3\u5E93\uFF0C\u7D22\u5F15\u53EA\u5B58\u4F4D\u7F6E\u4E0D\u5B58\u5185\u5BB9\uFF09\u3002
+
+\u8D44\u4EA7\u521B\u5EFA/\u590D\u5236\uFF1AWeb \u7BA1\u7406\u53F0\u6216 siming skill / siming agent \u547D\u4EE4\u7EC4\uFF1B
+\u8DE8\u5B9E\u4F8B\u8FC1\u79FB\u8D70 siming export / siming install\u3002
+
+----------------------------------------------------------------
+\u56DB\u3001\u63A5\u5165\u9A8C\u8BC1\u6B65\u9AA4
+----------------------------------------------------------------
+
+\u63A5\u5165\u6210\u529F\u7684\u5224\u5B9A\u52A8\u4F5C\u2014\u2014\u521B\u5EFA\u9996\u4E2A\u4EFB\u52A1\u5E76\u8DD1\u901A\u9996\u8282\u70B9\uFF1A
+
+1. \u786E\u8BA4 server \u53EF\u8FBE\uFF1Asiming healthcheck\uFF08\u6216 siming doctor \u5168\u9762\u81EA\u68C0\uFF09
+2. \u521B\u5EFA\u9996\u4EFB\u52A1\uFF1A\u52A0\u8F7D task-create skill\uFF08\u6309\u5176\u5339\u914D\u89C4\u5219\u9009\u6A21\u677F\u4E0E\u526A\u679D\uFF09\uFF0C
+   \u6216\u7ECF MCP \u5DE5\u5177 siming_task\uFF08action: create\uFF09
+3. \u63A8\u8FDB\u9996\u8282\u70B9\uFF1A\u6309\u4EFB\u52A1 context \u8FD4\u56DE\u7684\u8282\u70B9\u63D0\u793A\u8BCD\u6267\u884C\u5E76 advance
+4. \u9996\u8282\u70B9\u8DD1\u901A = \u9879\u76EE\u58F0\u660E\u3001\u6A21\u677F\u3001\u8D44\u4EA7\u3001\u94FE\u8DEF\u5168\u90E8\u5C31\u7EEA
+
+================================================================
+\u672C\u6307\u5BFC\u968F siming CLI \u7248\u672C\u53D1\u5E03\u6F14\u8FDB\uFF08\u7EAF\u672C\u5730\u9759\u6001\u6587\u672C\uFF0C\u96F6\u7F51\u7EDC\u4F9D\u8D56\uFF09\u3002
+================================================================
+`;
+function getGuideText() {
+  return GUIDE_TEXT;
+}
+
+// src/commands/guide.ts
+function createGuideCommand() {
+  const guide = new Command13("guide").description("Print the onboarding guide for connecting a new project to siming workflows").allowExcessArguments(false).action(() => {
+    console.log(getGuideText());
+  });
+  return guide;
+}
+
+// src/commands/settings/command.ts
+import { Command as Command14 } from "commander";
 import { EnumRegistryCategorySchema as EnumRegistryCategorySchema2, EnumRegistryUpdateSchema as EnumRegistryUpdateSchema2 } from "@siming-org/core";
 function createSettingsCommand() {
-  const settings = new Command13("settings").description("Settings (enum registries)");
+  const settings = new Command14("settings").description("Settings (enum registries)");
   withCommonOpts(settings.command("enums [category]"), "fancy").description("Show enum registry (all 7 categories, or one category)").action(async (category, opts) => {
     const client = createClient(opts.url);
     const catR = category ? EnumRegistryCategorySchema2.safeParse(category) : null;
@@ -4245,13 +4891,13 @@ function readStdin() {
 }
 
 // src/commands/server/command.ts
-import { Command as Command14 } from "commander";
+import { Command as Command15 } from "commander";
 import { spawn as spawn2 } from "child_process";
 import { VERSION as VERSION4, SIMING_CONFIG_KEYS as SIMING_CONFIG_KEYS2 } from "@siming-org/core";
 
 // src/commands/server/daemon.ts
 import { execFileSync } from "child_process";
-import { closeSync, existsSync as existsSync6, lstatSync, mkdirSync as mkdirSync5, openSync, readFileSync as readFileSync9, renameSync as renameSync3, rmSync as rmSync3, writeFileSync as writeFileSync5 } from "fs";
+import { closeSync, existsSync as existsSync6, lstatSync, mkdirSync as mkdirSync4, openSync, readFileSync as readFileSync11, renameSync as renameSync3, rmSync as rmSync3, writeFileSync as writeFileSync4 } from "fs";
 import { join as join6, resolve as resolve2 } from "path";
 import { spawn } from "child_process";
 
@@ -4281,7 +4927,7 @@ var FALLBACK_CLK_TCK = 100;
 function ensureRuntimeDir() {
   const st = lstatSync(runtimeDir(), { throwIfNoEntry: false });
   if (st === void 0) {
-    mkdirSync5(runtimeDir(), { mode: 448, recursive: true });
+    mkdirSync4(runtimeDir(), { mode: 448, recursive: true });
     return;
   }
   if (st.isSymbolicLink()) {
@@ -4305,7 +4951,7 @@ function readPidFile() {
   try {
     const st = lstatSync(pidfilePath(), { throwIfNoEntry: false });
     if (st === void 0 || st.isSymbolicLink()) return null;
-    const parsed = JSON.parse(readFileSync9(pidfilePath(), "utf-8").trim());
+    const parsed = JSON.parse(readFileSync11(pidfilePath(), "utf-8").trim());
     if (typeof parsed.pid !== "number" || typeof parsed.startedAt !== "number" || typeof parsed.port !== "number") {
       return null;
     }
@@ -4333,7 +4979,7 @@ function writePidFile(info2) {
     }
   }
   const tmp = `${pidfilePath()}.tmp-${process.pid}`;
-  writeFileSync5(tmp, `${JSON.stringify(info2)}
+  writeFileSync4(tmp, `${JSON.stringify(info2)}
 `, "utf-8");
   renameSync3(tmp, pidfilePath());
   return true;
@@ -4346,7 +4992,7 @@ function removePidFile(expectedPid) {
 }
 function readCmdline(pid) {
   try {
-    const raw = readFileSync9(`/proc/${pid}/cmdline`);
+    const raw = readFileSync11(`/proc/${pid}/cmdline`);
     const joined = raw.toString().split("\0").filter((s) => s.length > 0).join(" ");
     if (joined.length > 0) return joined;
   } catch {
@@ -4375,7 +5021,7 @@ function isSimingDaemonCmdline(cmdline, expectedEntry) {
 }
 function readProcessStartMs(pid) {
   try {
-    const stat = readFileSync9(`/proc/${pid}/stat`, "utf-8");
+    const stat = readFileSync11(`/proc/${pid}/stat`, "utf-8");
     const rest = stat.slice(stat.lastIndexOf(")") + 2);
     const fields = rest.split(" ");
     const starttimeJiffies = Number(fields[19]);
@@ -4404,7 +5050,7 @@ function readProcessStartMs(pid) {
 }
 function readBtimeFromProcStat() {
   try {
-    const stat = readFileSync9("/proc/stat", "utf-8");
+    const stat = readFileSync11("/proc/stat", "utf-8");
     for (const line of stat.split("\n")) {
       if (line.startsWith("btime ")) {
         const v = Number(line.slice(6).trim());
@@ -4455,7 +5101,7 @@ function sleep(ms) {
 function readLogTail(lines = 30) {
   const st = lstatSync(logfilePath(), { throwIfNoEntry: false });
   if (st === void 0 || st.isSymbolicLink()) return null;
-  const content = readFileSync9(logfilePath(), "utf-8");
+  const content = readFileSync11(logfilePath(), "utf-8");
   const all = content.split("\n");
   if (all.at(-1) === "") all.pop();
   return all.slice(-lines);
@@ -4521,7 +5167,7 @@ function displayUrl(host, port) {
 // src/commands/server/command.ts
 var MONGO_ERROR_PATTERN = /server selection|ECONNREFUSED|ENOTFOUND|EACCES|authentication/i;
 function createServerCommand() {
-  const server = new Command14("server").description("\u7BA1\u7406 siming \u670D\u52A1\uFF08API \u4E0E Web UI \u540C\u8FDB\u7A0B\u540C\u7AEF\u53E3\uFF09");
+  const server = new Command15("server").description("\u7BA1\u7406 siming \u670D\u52A1\uFF08API \u4E0E Web UI \u540C\u8FDB\u7A0B\u540C\u7AEF\u53E3\uFF09");
   server.command("start").description("\u542F\u52A8 siming \u670D\u52A1\uFF08\u9ED8\u8BA4\u5B88\u62A4\u6A21\u5F0F\uFF0C\u65E5\u5FD7\u5199\u5165 /tmp/siming/\uFF09").option("--port <port>", "\u76D1\u542C\u7AEF\u53E3\uFF08\u9ED8\u8BA4 7777\uFF1B\u4E5F\u53EF\u7ECF PORT \u73AF\u5883\u53D8\u91CF/\u914D\u7F6E\u6587\u4EF6\u914D\u7F6E\uFF09").option("--mongo-uri <uri>", "MongoDB \u8FDE\u63A5\u4E32\uFF08\u4E5F\u53EF\u7ECF SIMING_MONGO_URI/\u914D\u7F6E\u6587\u4EF6\u914D\u7F6E\uFF09").option("--foreground", "\u524D\u53F0\u8FD0\u884C\uFF08\u8C03\u8BD5/systemd \u573A\u666F\uFF09\uFF0CCtrl+C \u4F18\u96C5\u9000\u51FA\uFF1B\u4E0D\u5199 pidfile", false).action(async (opts) => {
     process.exitCode = await startAction(opts);
   });
@@ -4873,7 +5519,7 @@ function reportPortConflict(port) {
 }
 
 // src/index.ts
-var program = new Command15();
+var program = new Command16();
 program.name("siming").description("\u53F8\u547D \xB7 Siming \u2014 AI coding workflow management platform").version(VERSION5);
 program.command("healthcheck").description("Check if the siming server is reachable").option("--url <url>", "server base URL").action(async (opts) => {
   await healthcheckCommand(opts);
@@ -4892,6 +5538,7 @@ program.addCommand(createExportCommand());
 program.addCommand(createInstallCommand());
 program.addCommand(createInitCommand());
 program.addCommand(createDoctorCommand());
+program.addCommand(createGuideCommand());
 program.addCommand(createSettingsCommand());
 program.addCommand(createServerCommand());
 export {